Some time ago, I published a post explaining how to create and manage a portable development environment in Python using venv. In combination with pyenv, this allows you to install modules and packages for a desired version of Python.

uv is an extremely fast dependency and environment manager for Python development. In this post, I summarize how to install uv and how to use it.

Setup

The easiest way to install uv is with Homebrew:

brew install uv

However, direct installation is also possible:

curl -LsSf https://astral.sh/uv/install.sh | sh

Usage

To highlight the advantages of using uv, I will later briefly show the old approach to managing dependencies in a Python environment and how to migrate a project set up in this way to a uv project.

Approach with uv

A new project can be initialized with:

uv init APP_NAME

Alternatively, a uv project can be initialized in an existing folder by navigating to the folder and then entering the same command, but without a project name:

uv init

This creates a simple Python project, including version control with git (in the .git folder) and environment management (in the .venv folder). Arguments can also be specified during initialization, such as:

• --app with which an application is created, or
• --lib which is used to create a shareable library.

New dependencies are then installed with:

uv add xxxx

Dependencies can be deleted with:

uv remove xxx

The dependencies have now been installed and specified in the pyproject.toml file so that the uv environment can be shared. The dependencies can also be viewed with:

uv tree

Code is executed by uv with:

uv run main.py

If you now delete the virtual environment (i.e., the .venv folder), uv can continue to execute the code because it automatically reinstalls all dependencies in a virtual environment (referencing the project.toml file).

If you want to set up the virtual environment automatically without having to execute the code, you can do so with:

uv sync

To install a specific version of Python, use:

uv python install 3.10 3.11 3.12

And the version to be used can then be selected with:

uv python pin 3.11

Available versions of Python can be queried as follows:

uv python list

The old approach

A virtual environment is created with:

python -m venv .venv

It is activated with:

source .venv/bin/activate

Dependencies are installed in the now activated environment using pip with:

pip install xxxx

To save the installed dependencies for later reproducibility, use the following command:

pip freeze > requirements.txt

The file obtained in this way can install dependencies in an environment (especially one that has not yet been set up) using:

pip install -r requirements.txt

Code (e.g., in a file named main.py) is then executed with:

python main.py

And the environment can be deactivated with:

deactivate

If you want to change the Python version, you must install pyenv, for example, so that the desired version can be installed and activated, and then set up the virtual environment (.venv) again as described above.

Migration to uv

If you have a project set up with only pip (or uv pip), you can migrate it to uv by first initializing a uv project:

uv init

After that, all dependencies can be installed with:

uv add -r requirements.txt

The requirements.txt file is then no longer necessary and can be deleted.