uv

https://docs.astral.sh/uv/

An extremely fast Python package and project manager, written in Rust.

快速开始

安装

手动安装

curl -LsSf https://astral.sh/uv/install.sh | sh
# or
wget -qO- https://astral.sh/uv/install.sh | sh

pip（不建议，要用 uv 就抛弃 pip 了）

pip install uv

安装 python

• uv python install: Install Python versions.
• uv python list: View available Python versions.
• uv python find: 列出已安装的 python versions
• uv python pin: Pin the current project to use a specific Python version.
• uv python uninstall: Uninstall a Python version.

管理项目

Creating and working on Python projects, i.e., with a pyproject.toml.

• ==uv add: Add a dependency to the project.==
• uv remove: Remove a dependency from the project.
• uv init: Create a new Python project.
• ==uv sync: Sync the project's dependencies with the environment.==
• uv lock: Create a lockfile for the project's dependencies.
• uv tree: View the dependency tree for the project.
• uv build: Build the project into distribution archives.
• uv publish: Publish the project to a package index.

安装工具

Running and installing tools published to Python package indexes, e.g., ruff or black.

• uvx / uv tool run: Run a tool in a temporary environment.
• uv tool install: Install a tool user-wide.
• uv tool uninstall: Uninstall a tool.
• uv tool list: List installed tools.
• uv tool update-shell: Update the shell to include tool executables.

其他

Managing and inspecting uv's state, such as the cache, storage directories, or performing a self-update:

• uv cache clean: Remove cache entries.
• uv cache prune: Remove outdated cache entries.
• uv cache dir: Show the uv cache directory path.
• uv tool dir: Show the uv tool directory path.
• uv python dir: Show the uv installed Python versions path.
• uv self update: Update uv to the latest version.

Python 安装与版本管理

$ uv python install 3.12
# multiple
$ uv python install 3.11 3.12 

如果环境中已有 Python，uv 也会自动使用之，且不需要额外的配置

虚拟环境

uv supports creating virtual environments, e.g., to create a virtual environment at .venv:

uv venv

A specific name or path can be specified,

uv venv <name>

这将会在当前目录新建一个 <name> 目录

A Python version can be requested, e.g., to create a virtual environment with Python 3.11:

uv venv --python 3.11

Note this requires the requested Python version to be available on the system. However, if unavailable, uv will download Python for you. See the Python version documentation for more details.

---

To exit a virtual environment, use the deactivate command:

deactivate

包管理

安装

$ uv pip install flask

To install a package with optional dependencies enabled, e.g., Flask with the "dotenv" extra:

$ uv pip install "flask[dotenv]"

一次安装多个包

$ uv pip install flask ruff

指定版本

$ uv pip install 'ruff==0.3.0'
$ uv pip install 'ruff>=0.2.0'

从本地安装

$ uv pip install "ruff @ ./projects/ruff"

从 GitHub 安装

$ uv pip install "git+https://github.com/astral-sh/ruff"

To install a package from GitHub at a specific reference:

$ # Install a tag
$ uv pip install "git+https://github.com/astral-sh/ruff@v0.2.0"

$ # Install a commit
$ uv pip install "git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d"

$ # Install a branch
$ uv pip install "git+https://github.com/astral-sh/ruff@main"

Install from a requirements.txt file:

$ uv pip install -r requirements.txt

See the uv pip compile documentation for more information on requirements.txt files.

Install from a pyproject.toml file:

$ uv pip install -r pyproject.toml

Install from a pyproject.toml file with optional dependencies enabled, e.g., the "foo" extra:

$ uv pip install -r pyproject.toml --extra foo

Install from a pyproject.toml file with all optional dependencies enabled:

$ uv pip install -r pyproject.toml --all-extras

卸载包

$ uv pip uninstall <pkg-name>

To uninstall multiple packages, e.g., Flask and Ruff:

$ uv pip uninstall flask ruff

查看包信息

To list all of the packages in the environment:

$ uv pip list
# in a JSON format
$ uv pip list --format json 
# in a requirements.txt format
$ uv pip freeze

To show information about an installed package, e.g., numpy:

$ uv pip show numpy

Multiple packages can be inspected at once.

---

It is possible to install packages with conflicting requirements into an environment if installed in multiple steps.

To check for conflicts or missing dependencies in the environment:

$ uv pip check

依赖配置

依赖声明

最佳实践是将依赖项声明在静态文件中，而不是通过临时安装来修改环境。一旦定义了依赖项，就可以将其锁定，以创建一个一致且可重现的环境。

Using pyproject.toml

The pyproject.toml file is the Python standard for defining configuration for a project.

To define project dependencies in a pyproject.toml file:

pyproject.toml

[project]
dependencies = [
  "httpx",
  "ruff>=0.3.0"
]

To define optional dependencies in a pyproject.toml file:

pyproject.toml

[project.optional-dependencies]
cli = [
  "rich",
  "click",
]

Each of the keys defines an "extra", which can be installed using the --extra and --all-extras flags or package[<extra>] syntax.

Using requirements.in

通常也会使用轻量级的 requirements.txt 格式来声明项目的依赖关系。每个依赖项都在单独的一行中定义。通常，这个文件被称为 requirements.in，以便与用于锁定依赖关系的 requirements.txt 区分开来。

# requirements.in
httpx
ruff>=0.3.0

Optional dependencies groups are not supported in this format.

锁定环境

锁定是指获取一个依赖项，例如 ruff，并将其确切版本写入文件。当处理多个依赖项时，锁定确切版本是很有用的，这样可以重现环境。如果不进行锁定，依赖项的版本可能会随着时间、使用不同工具或跨平台而变化。

uv 允许依赖项以 requirements.txt 格式锁定。建议使用标准的 pyproject.toml 来定义依赖项，但其他依赖格式也受到支持。

To lock dependencies declared in a pyproject.toml:

$ uv pip compile pyproject.toml -o requirements.txt

Note by default the uv pip compile output is just displayed and --output-file / -o argument is needed to write to a file.

To lock dependencies declared in a requirements.in:

$ uv pip compile requirements.in -o requirements.txt

To lock dependencies declared in multiple files:

$ uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt

---

更新环境

在使用输出文件时，uv 会考虑现有输出文件中固定的版本。如果某个依赖被固定，那么在后续的编译运行中它将不会被升级。例如：

echo "ruff==0.3.0" > requirements.txt
$ echo "ruff" | uv pip compile - -o requirements.txt
# This file was autogenerated by uv via the following command:
#    uv pip compile - -o requirements.txt
ruff==0.3.0

使用 --upgrade-package flag 来升级依赖

uv pip compile - -o requirements.txt --upgrade-package ruff

使用 --upgrade flag 来 ==升级所有依赖==

uv pip compile - -o requirements.txt --upgrade

同步环境

依赖项可以直接从它们的定义文件或已编译的 requirements.txt 文件中使用 uv pip install 安装。

使用 uv pip install 安装时，已经安装的包将不会被移除，除非它们与锁定文件冲突。这意味着环境中可以存在未在锁定文件中声明的依赖项，这对可复现性来说并不是很好。为了确保环境与锁定文件完全匹配，请改用 uv pip sync。

uv pip sync requirements.txt
uv pip sync pyproject.toml

Tools

The uvx command invokes a tool without installing it.

For example, to run ruff:

uvx ruff
# exactly equivalent to:
uv tool run ruff

Tools are installed into temporary, isolated environments when using uvx.

---

When uvx ruff is invoked, uv installs the ruff package which provides the ruff command. However, sometimes the package and command names differ.

The --from option can be used to invoke a command from a specific package, e.g. http which is provided by httpie:

$ uvx --from httpie http

---

若要指定工具版本，use command@<version>:

uvx ruff@0.3.0 check
uvx ruff@latest check

The --from option can also be used to specify package versions, as above:

uvx --from 'ruff==0.3.0' ruff check

Or, to constrain to a range of versions:

uvx --from 'ruff>0.2.0,<0.3.0' ruff check

配置

uv supports persistent configuration files at both the project- and user-level.

Specifically, uv will search for a pyproject.toml or uv.toml file in the current directory, or in the nearest parent directory.

For tool commands, which operate at the user level, local configuration files will be ignored

If a ==pyproject.toml== file is found, uv will read configuration from the [tool.uv] table. For example, to set a persistent index URL, add the following to a pyproject.toml:

[[tool.uv.index]]
url = "https://test.pypi.org/simple"
default = true

uv will also search for ==uv.toml== files, which follow an identical structure, but omit the [tool.uv] prefix. 这个文件的优先级比 pyproject 高

[[index]]
url = "https://test.pypi.org/simple"
default = true

uv 还会在 ~/.config/uv/uv.toml 中发现系统级配置。

• 用户级和系统级配置必须使用 uv.toml 格式，而不是 pyproject.toml 格式，因为 pyproject.toml 是用于定义 Python 项目的。

• 如果同时发现项目级、用户级和系统级配置文件，设置将会合并。优先级：项目级 > 用户级配置 > 系统级配置。

• 通过命令行提供的设置 > 通过环境变量提供的设置 > 持久配置

• uv 接受一个 --no-config 命令行参数，当提供时，将禁用对任何持久配置的发现。

• uv 还接受一个 --config-file 命令行参数，该参数接受一个 uv.toml 的路径作为配置文件使用。当提供时，此文件将替代任何发现的配置文件

详细配置参数：https://docs.astral.sh/uv/reference/settings/#constraint-dependencies

项目化

https://docs.astral.sh/uv/concepts/projects/

uv 主要使用 pyproject.toml 来管理项目

• 创建项目：uv init / uv init <pro-name>

• 添加/移除依赖：uv add <lib-name> / uv remove <lib-name>

  • 将 requirements.txt 中的依赖转移到 pyproject.toml 中：uv add -r requirements.txt

• 更新依赖：uv sync