Introduction

Everyone is promoting uv's speed (UV: The Ultimate Python Package Manager - 100x Faster than pip), but for our lab, where we may need to migrate Python environments across multiple machines, uv's convenience in reproducing environments is also worth noting.

Although I have been trying my best to recommend uv to my labmates, they are still heavily reliant on conda and unwilling to try new tools. Therefore, I decided to write a tutorial to introduce how to use uv, hoping to push forward a change in lab environment management.

Installing uv

Official Documentation

On Windows, I still recommend using winget to install:

On Linux/macOS, you can refer to the official documentation and use curl/wget to install:

Initializing a uv Environment

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

Or if you need to migrate an existing Python project to a uv environment, you can run the following in the project directory:

This will create the following files in the project directory:

1. .git, .gitignore, README.md need no explanation.
2. main.py is a sample Python file; you can delete it if not needed.
3. pyproject.toml is the configuration file for the Python project, which records metadata, dependencies, etc. Its content looks roughly 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 is used to specify the Python version for the current project.

Specifying the Python Version

Edit the requires-python field in the pyproject.toml file to specify the Python version required for the current project, for example: ==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, in the .venv folder. You can then activate the virtual environment by referring to its output, for example:

Managing Project Dependencies

Basic Usage

When you need to install a new dependency, you can use the following command:

In practice, you just replace the previous 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 of the pyproject.toml file and updates the uv.lock lock file to ensure reproducibility of dependency versions. The uv.lock file does not need manual editing, but it is crucial for environment reproducibility; do not put it in .gitignore.

For example, after installing requests, pyproject.toml will only have an additional requests dependency, while uv.lock will record detailed version information for requests and all its sub-dependencies. You can use the uv tree command to view the dependency tree:

If you no longer need a dependency, you can remove it with the following command:

Mirror Sources

If you need to change the PyPI mirror source, you can add the following content to the pyproject.toml file (using the NJU mirror as an example):

index-url in pip

Some packages are published on their own PyPI mirrors, for example, the pip install command for torch (see torch official documentation) is as follows:

You need to refer to Using uv with PyTorch and add the following content to the pyproject.toml file:

Otherwise, the CUDA version of torch and torchvision will not be installed; instead, the CPU version will be installed.

Here, we first define an index source named pytorch-cu130, with the url set to the --index-url given in the torch documentation above, but I directly replaced it with the NJU mirror https://mirror.nju.edu.cn/pytorch/whl/cu130. Then in tool.uv.sources, we specify that the torch and torchvision packages should be installed from this index source (note: the marker specifies that the pytorch-cu130 index is used only when the operating system is Linux or Windows. For other operating systems, such as macOS, this configuration is ignored and the default source is used).

Reproducing the Environment

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

If you want to reproduce the same environment in another project, you can copy the pyproject.toml, uv.lock, and .python-version files to the target project directory, update the project information in pyproject.toml, and then run the same command:

Building and Publishing Packages

If you are writing a PyPI package that others can install, you also need to consider which dependencies are development dependencies and which are runtime dependencies. Development dependencies should be installed using the uv add --dev [package-name] command.

After that, you need to fill in the project information in the pyproject.toml file, such as author, license, and build information. Considering that most research work does not involve publishing packages, I won't go into detail here. You can refer to the following content for understanding:

Then you can build and publish the package using the following commands:

Other Useful Commands

1. uv cache clear: Clear the uv cache to free up disk space.
2. uv tree: View the dependency tree of the current project.
3. uv run main.py: Equivalent to running python main.py after activating the virtual environment; can be used to run Python scripts in the project.
4. uvx [script-name]: Run a tool. Some Python packages provide command-line tools; you can use the uvx command to run them, for example, uvx NJUlogin -h.