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
Level 1 · The editor
Level 2 · Checking and fixing code
Level 3 · Trying code out
Level 4 · Other people's code
Level 5 · Building the project
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.
$ 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.pyWorked 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.