uv Getting Started Tutorial -- Python Package and Environment Management Tool

In Python development, package management and environment isolation are problems that every developer encounters. Whether it is the slowness of pip, the cumbersomeness of virtualenv, or the bloat of conda,uvall make developers look forward to a more efficient solution.

What is uv?

uv is a Python package manager and environment manager developed by Astral in Rust. Its main goal is to provide performance 10-100 times faster than existing tools while maintaining a simple and intuitive user experience.

uv can replace tools such as pip, virtualenv, pip-tools, and pyenv, providing one-stop services for dependency management, virtual environment creation, and Python version management.

Advantages of uv

Extremely fast: Because it is written in Rust, uv's performance far exceeds that of pip and other package management tools, and the speed of installing dependencies can be improved by 10-100 times.
Integrated functionality: It integrates dependency resolution, package installation, environment management, and Python version management into one, without the need to install and learn multiple tools.
Deterministic builds: uv generates auv.lockfile, ensuring that exactly the same dependency versions can be installed in any environment, avoiding the "works on my machine" problem.
Compatibility with existing tools: uv can handlerequirements.txtandpyproject.toml, and can seamlessly replace pip in existing workflows.

Installing uv

Installing on macOS

It is recommended to install via Homebrew:

brew install uv

Or use the official installation script:

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

Installing on Linux

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

Installing on Windows

Using Winget:

winget install uv

Or use the official installation script (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

After installation, verify whether it was successful:

uv --version

The output is similar to the following, indicating that the installation was successful:

uv 0.8.14 (Homebrew 2025-08-28)

1. Managing Python Versions

uv has built-in Python version management functionality, so there is no need to install additional tools such as pyenv.

View available Python versions:

uv python list

The output result is similar to the following:

cpython-3.14.0rc2-macos-aarch64-none                 <download available>
cpython-3.13.7-macos-aarch64-none                    <download available>
cpython-3.12.11-macos-aarch64-none                   <download available>
cpython-3.11.13-macos-aarch64-none                   <download available>
cpython-3.10.18-macos-aarch64-none                   <download available>
cpython-3.9.6-macos-aarch64-none                     /usr/bin/python3
pypy-3.11.13-macos-aarch64-none                      <download available>

Install a specific version of Python:

# 安装最新的 Python 3.12
uv python install 3.12

# 安装特定版本
uv python install 3.11.6

# 安装 PyPy 版本
uv python install pypy3.10

Set the global default Python version:

uv python default 3.12

Pin the Python version for the current project (this will create a.python-versionfile):

uv python pin 3.12

After executing this command, a .python-version file will be generated in the current project directory. When opened, it displays the version number content:

3.12

2. Managing Virtual Environments

Create a virtual environment:

# 在当前目录创建名为 .venv 的虚拟环境（使用系统默认 Python）
uv venv

# 使用指定 Python 版本创建虚拟环境
uv venv --python 3.12

Activate the virtual environment:

# macOS / Linux
source .venv/bin/activate

# Windows（PowerShell）
.venv\Scripts\activate

Exit the virtual environment:

deactivate

In daily development, you can useuv runto directly run scripts without manually activating the virtual environment.

3. Package Management (pip Compatibility Mode)

uv provides a command-line interface fully compatible with pip, which can directly replace pip commands in existing workflows:

Install packages:

# 安装最新版本
uv pip install requests

# 安装特定版本
uv pip install requests==2.31.0

# 从 requirements.txt 批量安装
uv pip install -r requirements.txt

Upgrade packages:

uv pip install --upgrade requests

Uninstall packages:

uv pip uninstall requests

View installed packages:

uv pip list

Export the current environment's dependencies to requirements.txt:

uv pip freeze > requirements.txt

4. Project Management (Recommended Approach)

uv supports apyproject.toml-centered modern project management approach, which is more recommended than pip mode, especially suitable for team collaboration and multi-environment deployment.

Initializing a Project

uv init my_project
cd my_project

This will create the following basic project structure:

my_project/
├── pyproject.toml    # 项目配置和依赖声明
├── .python-version   # 固定 Python 版本
├── README.md
└── main.py

Adding and Removing Dependencies

In project mode, it is recommended to useuv addanduv removeto manage dependencies; they will automatically updatepyproject.tomlanduv.lock：

# 添加生产依赖
uv add requests

# 添加指定版本的依赖
uv add "requests>=2.31.0"

# 添加开发依赖（只在开发环境使用，如测试框架）
uv add --dev pytest ruff

# 移除依赖
uv remove requests

Installing All Project Dependencies (uv sync)

After cloning the project or updatingpyproject.toml, run the following command to install all dependencies with one click:

uv sync

uv sync explanation:Similar topip install -r requirements.txt, it will, based onpyproject.tomlanduv.lockinstall all dependencies, ensuring that the environment is exactly the same as other developers'. If installation is slow, you can, inpyproject.tomlset a domestic mirror source:
[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

Generating/Updating Lock Files

uv lock

This command will parsepyproject.toml's dependencies and generate (or update) theuv.lockfile.uv.lockIt should be committed to the version control repository to ensure that all team members use exactly the same dependency versions.

5. Running Scripts (uv run)

uv runis a very practical command in uv, allowing you to, without manually activating the virtual environment,directly run scripts or commands. uv will automatically find and use the correct environment:

# 直接运行 Python 脚本
uv run main.py

# 运行项目中的测试
uv run pytest

# 运行任意命令（在虚拟环境的上下文中执行）
uv run python -c "import requests; print(requests.__version__)"

Usinguv runcompared with manually activating the environment has these advantages: you will not accidentally use the wrong Python version, nor will you forget to activate the environment and cause packages to not be found. It is especially suitable for use in CI/CD and script automation.

Migrating to uv

If you are using other tools, you can migrate to uv in the following ways:

Migrating from pip + virtualenv:

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 安装原有依赖
uv pip install -r requirements.txt

Migrating from pip-tools:

# 编译依赖（替代 pip-compile）
uv pip compile requirements.in -o requirements.txt

# 同步环境（替代 pip-sync）
uv pip sync requirements.txt

Migrating from poetry or pdm:

# 直接使用现有的 pyproject.toml
uv sync

Other Extensions

Python3Advanced Tutorial