Introduction

Everyone is touting uv's speed (UV: A Python Package Management Powerhouse - 100x Faster than pip), but for our lab’s need to migrate Python environments across multiple machines, uv’s ease of environment reproducibility is equally worth highlighting.

Although we’ve been actively recommending uv to colleagues, many still deeply rely on conda and are reluctant to try new tools. Therefore, I’ve decided to write this tutorial introducing uv’s usage, hoping to gently push forward a shift in how we manage lab environments.

Installing uv

Official Documentation

On Windows, I still recommend using winget:

On Linux/macOS, refer to the official documentation using curl or wget:

Initializing a uv Environment

If you need to initialize a new project, run the following in your workspace directory:

Or, if you want to migrate an existing Python project into a uv environment, run:

This will create the following files in your project directory:

1. .git, .gitignore, and README.md need no explanation.
2. main.py is just a sample Python file—delete it if not needed.
3. pyproject.toml is the configuration file for Python projects, storing metadata and dependencies. Its content looks like this: toml [project] name = "test-project" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.12" dependencies = []
4. .python-version specifies the Python version for the current project.

Specifying Python Version

Edit the requires-python field in pyproject.toml to specify the required Python version for your project, e.g., ==3.12, >=3.12, etc.

Then run the following command to install the specified Python version:

Creating a Virtual Environment

This command creates a virtual environment in the current project directory, named .venv. Afterward, follow the output instructions to activate the environment, such as:

Managing Project Dependencies

Basic Usage

To install a new dependency, use:

It’s essentially replacing pip install with uv add. However, this command not only installs the dependency into the virtual environment but also automatically writes the dependency information into the dependencies field in pyproject.toml, and updates the uv.lock lock file to ensure reproducible dependency versions. The uv.lock file should never be edited manually, but it is crucial for environment reproducibility—do not add it to .gitignore.

For example, after installing requests, pyproject.toml will only have one additional line: requests. Meanwhile, uv.lock records detailed version information for requests and all its sub-dependencies. Use the uv tree command to view the dependency tree:

If you no longer need a dependency, remove it using:

Mirror Sources

To switch to a different PyPI mirror, add the following to pyproject.toml (using Nanjing University’s mirror as an example):

pip index-url

Some packages are published on their own PyPI mirrors—for example, the pip installation command for torch (see PyTorch Official Documentation):

To use uv with PyTorch, refer to Using uv with PyTorch and add the following to pyproject.toml:

Otherwise, it will install the CPU version instead of the CUDA-enabled version of torch and torchvision.

First, define an index source named pytorch-cu130, with url set to the --index-url from the official document, though here I’ve replaced it with the Nanjing University mirror: https://mirror.nju.edu.cn/pytorch/whl/cu130. Then, under tool.uv.sources, specify that torch and torchvision must be installed from this index (note: marker ensures this applies only when the OS is Linux or Windows; macOS users will ignore this config and use the default source).

Reproducing the Environment

When you need to reproduce the Python environment on another machine, simply clone the project code and run:

To reproduce the same environment in another project, copy the pyproject.toml, uv.lock, and .python-version files into the target project directory, update the project info in pyproject.toml, then run the same command:

Building and Publishing Packages

If you’re developing a package for others to install, you’ll need to distinguish between development and runtime dependencies. Install development dependencies using uv add --dev [package-name].

You’ll also need to complete the project metadata in pyproject.toml, such as author, license, and build information. Since most research work doesn’t involve publishing packages, we won’t go into detail here—but you can refer to the following example for understanding:

After that, you can build and publish your package using:

Other Useful Commands

1. uv cache clear: Clear uv cache to free up disk space
2. uv tree: View the current project’s dependency tree
3. uv run main.py: Equivalent to activating the virtual environment and running python main.py; useful for running Python scripts in your project
4. uvx [script-name]: Run a tool. Some Python packages provide command-line tools—use uvx to run them, e.g., uvx NJUlogin -h.