Skip to content
BENIBIX Learn

Virtual Environments and uv

Level 4 · Other people's code

Each Python project gets its own packages in a virtual environment. A version manager swaps the language. And uv does both in one tool.

Course contentsLesson 11 of 13

After this lesson you can

  • Make and turn on a virtual environment
  • Switch versions with a version manager
  • Start a Python project with uv

12 mincovers 3 glossary entries

Worth reading first: Lockfiles and Version Pinning

How each project keeps its own packages and versions

A virtual environment is a folder that holds the Python packages for one project. While it is turned on, pip installs into that folder only. So two projects can use two versions of one package, and both still work. Python has had a tool to make one built in since version 3.3, in 2012.

Without one, every project shares the one Python your computer came with. Project A needs version 2.20 of a package and project B needs 2.31. Whichever you installed last wins, and the other project breaks.

Turning it on changes your terminal so that python and pip point into the folder. On macOS and Linux you run source .venv/bin/activate. On Windows the script sits in .venv\Scripts instead. The name (.venv) then appears at the start of the line, which is how you know it worked.

A version manager does the same for the language itself. It keeps several versions of Python or Node.js on one computer and switches between them. pyenv does it for Python and nvm for Node.js. A small file in the project, such as .nvmrc, names the version that project needs.

uv is a newer tool that does all of this at once. It is written in Rust, and its makers say it is 10 to 100 times faster than pip. One command sets up a project with its own virtual environment and lockfile. It can also install Python versions, so it replaces pyenv too.

With uv you add a package with uv add, not pip install. That way it lands in the project's list and its lockfile. You run code with uv run. It uses the project's own folder of packages, so you never have to turn it on.

The common mistake is forgetting to turn the environment on. pip then installs into the main Python, and the project cannot find the package. Look for (.venv) at the start of the line before you install.

console
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ pip install requests
(.venv) $ deactivate
$ uv init hello
$ cd hello
$ uv add requests
$ uv run main.py
The classic way, with venv and pip, then the same job with uv in four commands.
Each project has its own .venv and its own package versions. The version manager switches the language above them.

Worked example

Emma runs two Python projects

Emma's old project needs Python 3.10 and a 2021 version of a package. Her new one needs Python 3.12 and the latest version.

She sets up each one with uv, which installs both Python versions and keeps two sets of packages apart. Now, to switch projects, she just moves to the other folder.

The words for this lesson3

Check yourself

Why did pip put my package in the wrong place?

Finished this lesson?

Marking it complete also marks its 3 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.