Python Project Setup With uv – Virtual Environments and Package Management

Virtual Environments in Python

Virtual Environments are isolated Python environments that have their own site-packages. Basically, it means that each virtual environment has its own set of dependencies to third-party packages usually installed from PyPI.

Virtual environments are helpful if you develop multiple Python projects on the same machine. Also, when you distribute your Python code to others or on servers, virtual environments come in very handy to reproducibly create the same environment as on your development machine.

Today, we'll learn

• which tools exist to create isolated environments
• which tools help with package management in Python projects

Getting Started

What is uv?

Over the past years, Python developers have used venv and pip to create virtual environments and manage packages. However, uv is a new tool that combines the best of both worlds: virtual environments and package management. It is a modern tool that helps you to create isolated environments and manage packages in your Python projects. It is written in Rust and maintained by Astral.

Installing uv

Installing uv is straightforward. It is even published on PyPI, so you can install it with pip:

pip install uv

For more information about different installation methods, check out the official documentation.

Initializing a project

uv has an init command that will create a new Python project with a pyproject.toml file as well as a .gitignore file, a README.md, and a hello.py.

uv init my-test-project

Managing Python Versions

Other than the classic pip, uv manages versions of the Python interpreter for you.

With

uv python list

you get a list of all available Python versions on your system. Installing other versions is as simple as

uv python install 3.10.0

Managing Dependencies

uv uses a pyproject.toml file to manage dependencies. You can add dependencies with

uv add requests

The package names are the same as on PyPI.

With uv lock, you can create a Lockfile that holds all dependencies and their versions. This file can be used to install the exact same versions on other machines.

uv sync

uv sync is a command that installs all dependencies from the pyproject.toml file. It is similar to pip install -r requirements.txt.

Ad-hoc environments

One of the killer features of uv is the ability to create ad-hoc environments. This means that you can create a new environment with a single command and run a Python script in it.

Let's say, we want a project in Python 3.10 with the requests package. We can create a new environment with

Using pyenv and pip, we would have to create a new virtual environment, activate it, and install the package:

pyenv install 3.10
pyenv local 3.10
python -m venv .venv
source .venv/bin/activate
pip install requests
python hello.py

Using uv, this can be done with a single command:

uv run --python 3.10 --with requests python hello.py

Conclusion

uv is a modern tool that combines the best of both worlds: virtual environments and package management. It is a great tool to manage dependencies in your Python projects. Give it a try and let me know what you think!