uv 是一个全新的、由 Astral 团队（就是那个开发了 Ruff 的团队）采用 Rust 开发的高性能的 Python 包和项目管理工具。它的目标是取代传统的 pip 和 pip-tools，提供更快的速度和更强大的功能。简单来说，uv 就是 Python 开发的“加速器”！

主要亮点

一款替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等工具的全能解决方案。 比 pip 快 10 到 100 倍。 提供完整的项目管理，配备通用锁文件。 支持运行脚本，兼容内联依赖元数据。 可安装并管理 Python 版本。 能够运行和安装基于 Python 包发布的工具。 内置 pip 兼容接口，在保留熟悉 CLI 的同时提升性能。 支持 Cargo 式工作区，助力大型项目管理。 高效利用磁盘空间，全局缓存实现依赖去重。 无需 Rust 或 Python 环境，通过 curl 或 pip 即可安装。 全面支持 macOS、Linux 和 Windows 系统。

uv 显著的特点是速度：

uv 安装

uv 安装非常简单，且支持多种安装方式。

独立安装

uv 提供了一个独立的安装程序来下载和安装 uv。

macOS and Linux 安装 uv

使用 curl 下载安装脚本并使用 sh 命令执行安装脚本进行安装：

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

如果您的系统没有安装 curl，则可以使用 wget 安装：

wget -qO- https://astral.sh/uv/install.sh | sh

可以通过在 URL 中包含特定版本来请求该版本：

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

提示

使用前可以检查安装脚本，shell 命令：
curl -LsSf
https://astral.sh/uv/install.sh | less
或者，可以直接从 GitHub 下载安装程序或二进制文件。

Windows 系统安装 uv

使用irm iex 下载并执行安装：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后，可以在 powershell命令行或者cmd命令行下验证是否安装成：

在命令行执行不给定参数的 uv 命令会显示其用法帮助：

查看 uv 的版本可以使用：

uv version

可以通过在 URL 中包含特定版本来请求该版本：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.5.29/install.ps1 | iex"

提示

使用前可以检查安装脚本，Powershell 命令：
powershell -c "irm
https://astral.sh/uv/install.ps1 | more"
或者，可以直接从 GitHub 下载安装程序或二进制文件。

PyPI 安装

推荐使用pipx 命令：

pipx install uv

或者使用 pip 命令：

pip install uv

Cargo 安装

如果你的系统安装了 rust 可以通过 Cargo 安装（必须通过 Git 构建）

cargo install --git https://github.com/astral-sh/uv uv

Homebrew 安装

brew install uv

WinGet 安装

winget install --id=astral-sh.uv  -e

Scoop 安装

scoop install main/uv

升级更新 uv

uv self update

或者使用 pip 升级

pip install --upgrade uv

shell 自动补全

uv 命令自动补全

bash

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

Zsh

echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

fish

echo 'uv generate-shell-completion fish | source' >> ~/.config/fish/config.fish

Elvish

echo 'eval (uv generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv

PowerShell / pwsh

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

执行完毕重新启动powershell终端即可使用 uv 的命令行补全功能。

uvx 命令自动补全

bash

echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc

Zsh

echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc

fish

echo 'uvx --generate-shell-completion fish | source' >> ~/.config/fish/config.fish

Elvish

echo 'eval (uvx --generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv

PowerShell / pwsh

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

卸载 uv

清除缓存数据

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

清除 uv 或者 uvx 程序

macOS and Linux

rm ~/.local/bin/uv ~/.local/bin/uvx

Windows

$ rm $HOME\.local\bin\uv.exe
$ rm $HOME\.local\bin\uvx.exe

uv 主要功能

uv 功能丰富，提供从安装 Python 和运行简单脚本，到支持多 Python 版本和多平台的大型项目开发的各个方面。

uv 的功能可以分为多个模块，我们可以根据需要单独或组合使用这些模块。

Python 版本管理

安装和管理 Python 版本。

• uv python install：安装 Python 版本。
• uv python list：查看可用的 Python 版本。
• uv python find：查找已安装的 Python 版本。
• uv python pin：为当前项目指定使用的 Python 版本。
• uv python uninstall：卸载 Python 版本。

执行脚本

运行独立的 Python 脚本，例如example.py 。

• uv run：运行脚本。
• uv add --script：为脚本添加依赖。
• uv remove --script：从脚本中移除依赖。

项目管理

创建并管理包含 pyproject.toml 的 Python 项目。

• uv init：创建一个新项目。
• uv add：为项目添加依赖项。
• uv remove：从项目中移除依赖项。
• uv sync：同步项目依赖环境。
• uv lock：创建项目依赖锁文件。
• uv run：在项目环境中运行命令。
• uv tree：查看项目的依赖树。
• uv build：构建项目的发布包。
• uv publish：发布项目到包索引。

工具

运行和安装发布在 Python 包索引的工具（如 ruff 或 black）。

• uvx / uv tool run：在临时环境中运行工具。
• uv tool install：全局安装工具。
• uv tool uninstall：卸载工具。
• uv tool list：列出已安装的工具。
• uv tool update-shell：更新 shell，使工具可执行文件生效。

pip 接口

手动管理环境和包，适用于需要精细控制的传统工作流或场景。

创建虚拟环境（替代 venv 和 virtualenv）

• uv venv：创建一个新的虚拟环境。

管理环境中的包（替代 pip 和 pipdeptree）

• uv pip install：安装包到当前环境。
• uv pip show：显示已安装包的详细信息。
• uv pip freeze：列出已安装包及其版本。
• uv pip check：检查当前环境中的包是否兼容。
• uv pip list：列出已安装的包。
• uv pip uninstall：卸载包。
• uv pip tree：查看环境的依赖树。

锁定环境中的包（替代 pip-tools）

• uv pip compile：将需求文件编译为锁文件。
• uv pip sync：根据锁文件同步环境。

实用工具

管理和查看 uv 的状态，如：缓存、存储目录，或执行自更新：

• uv cache clean：清理缓存条目。
• uv cache prune：清理过期的缓存条目。
• uv cache dir：显示 uv 缓存目录路径。
• uv tool dir：显示 uv 工具目录路径。
• uv python dir：显示 uv 安装的 Python 版本路径。
• uv self update：将 uv 更新到最新版本。

查看 uv 帮助

简洁帮助：

uv --help
uv init --help

详细帮助：

uv help
uv help init

查看 uv 版本

uv version
uv --version      # Same output as `uv version`
uv -V             # Will not include the build commit and date
uv pip --version  # Can be used with a subcommand

安装 Python

安装最新版本的 Python

uv python install

提示

uv 并不使用 Python 官方发布的版本，而是使用来自 Astral 维护的 python-build-standalone 项目发布的 Python 版本。该项目支持CPython、PyPy、GraalPy版本。

安装指定版本的 Python

安装特定的 Python 版本：

uv python install 3.12

一条命令安装多个 Python 版本：

uv python install 3.11 3.12

安装符合约束条件的版本：

uv python install '>=3.8,<3.10'

安装特定的 Python 实现，例如 PyPy：

uv python install pypy@3.10

查看已安装和可用的 Python 版本：

uv python list

查看所有版本：

uv python list --all-versions

查看其他平台的 Python 版本：

uv python list --all-platforms

仅显示已安装的 Python 版本，并排除下载版本：

uv python list --only-installed

查找 Python 可执行文件：

uv python find

如：

uv python find >=3.11

uv python find --system

隐式安装（自动安装）Python

使用 uv 时可以自动下载需要的Python版本。

uv run --python 3.12 python -c 'print("hello world")'

重新安装 Python

uv python install --reinstall

使用现有的 Python 安装

uv 会使用系统中满足命令行要求的 Python 版本。

项目管理

创建新项目

uv init hello-world
cd hello-world

或者

mkdir hello-world
cd hello-world
uv init

uv 将创建以下文件：

.
├── .python-version
├── README.md
├── hello.py
└── pyproject.toml

项目结构

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── hello.py
├── pyproject.toml
└── uv.lock

项目 pyproject.toml 文件

pyproject.toml 文件包含有关项目的元数据

[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []

.python-version

该文件包含项目的默认 Python 版本。此文件告诉 uv 创建项目的虚拟环境时使用哪个 Python 版本。

.venv

该文件夹包含项目的虚拟环境，即 Python 环境，即 与系统的其余部分隔离。这是 uv 将安装项目依赖项的位置。

uv.lock

uv.lock是一个跨平台的 lockfile，其中包含有关项目的依赖。与 which 不同，它用于指定 project 中，lockfile 包含项目中安装的确切解析版本 环境。此文件应签入版本控制中，以实现一致且 跨计算机可重复安装。

管理依赖项

您可以使用该命令将依赖项添加到您的 .这也将更新 lockfile 和项目环境：pyproject.toml

uv add requests

可以指定版本约束或替代源

# Specify a version constraint
uv add 'requests==2.31.0'

# Add a git dependency
uv add git+https://github.com/psf/requests

要删除包：

uv remove requests

升级软件包：

uv lock --upgrade-package requests

手动更新环境(Windows)：

uv sync

source .venv\Scripts\activate
flask run -p 3000
python example.py

手动更新环境(macOS 和 Linux):

uv sync

source .venv/bin/activate
flask run -p 3000
python example.py

构建包

uv build可用于为您的 项目。

默认情况下，将在当前目录中构建项目，并将构建的 子目录中的工件：uv builddist/

uv build
ls dist/

发布包

使用 uv publish 发布Python包：

uv publish

运行脚本

Python 脚本是用于独立执行的文件，例如，使用 .用 UV 执行脚本可确保无需手动管理即可管理脚本依赖项 环境。 python <脚本>.py

运行没有依赖项的脚本

如果您的脚本没有依赖项，则可以使用 ：uv run

example.py

print("Hello world")

uv run example.py

向脚本提供参数：

uv run example.py test


uv run example.py hello world!

直接从 stdin 读取您的脚本：

echo 'print("hello world!")' | uv run -

uv run - <<EOF
print("hello world!")
EOF

运行具有依赖项的脚本

当您的脚本需要其他软件包时，必须将它们安装到 脚本运行。UV 更喜欢按需创建这些环境，而不是使用长期 具有手动管理的依赖项的虚拟环境。这需要显式声明 脚本所需的依赖项。通常，建议使用项目或内联元数据来声明 dependencies，但 UV 也支持每次调用请求依赖项。

例如，以下脚本需要 .rich

example.py

import time
from rich.progress import track

for i in track(range(20), description="For example:"):
    time.sleep(0.05)

使用以下选项请求依赖项：--with

uv run --with rich example.py

创建 Python 脚本

Python 最近为内联脚本元数据添加了标准格式。 它允许选择 Python 版本和定义依赖项。用于 使用内联元数据初始化脚本：uv init --script

uv init --script example.py --python 3.12

声明脚本依赖项

内联元数据格式允许在脚本本身中声明脚本的依赖项。

UV 支持为您添加和更新内联脚本元数据。用于声明 脚本的依赖项：uv add --script

uv add --script example.py 'requests<3' 'rich'

这将在脚本顶部添加一个部分，使用 TOML 声明依赖项：script

example.py

# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

使用不同的 Python 版本

uv 允许在每次脚本调用时请求任意 Python 版本，例如：

example.py

import sys

print(".".join(map(str, sys.version_info[:3])))

运行：

# Use the default Python version, may differ on your machine
uv run example.py

指定Python版本

# Use a specific Python version
uv run --python 3.10 example.py

包管理

将包安装到虚拟环境中，如 numpy：

uv pip install numpy

一次安装多个包:

uv pip install numpy pandas

安装带有约束的包，例如安装 Ruff v0.2.0 或者更新版本：

uv pip install 'ruff>=0.2.0'

安装特定版本的包，例如安装 Ruff v0.3.0：

uv pip install 'ruff==0.3.0'

从本地磁盘安装包：

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

从 GitHub 安装包：

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

从 GitHub 安装特定的包：

# 安装某个标签
uv pip install "git+https://github.com/astral-sh/ruff@v0.2.0"

# 安装某个提交
uv pip install "git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d"

# 安装某个分支
uv pip install "git+https://github.com/astral-sh/ruff@main"

可编辑包

可编辑包指不需要重新安装，可以通过修改源代码使更改生效。

将当前项目安装为可编辑包：

uv pip install -e .

将另一个目录中的项目安装为可编辑包：

uv pip install -e "ruff @ ./project/ruff"

从文件安装包

通过标准文件格式一次性安装多个包。

从 requirements.txt 文件安装：

uv pip install -r requirements.txt

从 pyproject.toml 文件安装：

uv pip install -r pyproject.toml

从 pyproject.toml 文件安装时启用可选依赖项：

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

从 pyproject.toml 文件安装时启用所有可选依赖项：

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

卸载包

卸载包：

uv pip uninstall flask
uv pip uninstall flask ruff

列出已安装的包

列出已安装的包：

uv pip list

以 JSON 格式列出包：

uv pip list --format json

以 requirements.txt 格式列出环境中所有包：

uv pip freeze

检查包信息

查看已安装包的信息：

uv pip show numpy

验证环境

如果在多个步骤中安装了包，可能会将具有冲突要求的包安装到同一个环境中。

检查环境中是否有冲突或缺失的依赖项：

uv pip check

Python 环境（虚拟环节）

创建虚拟环境

uv venv

指定特定的名称或路径

uv venv my-name

为虚拟环境指定 Python解释器版本：

uv venv --python 3.11

提示

注意，这要求所请求的 Python 版本已安装在系统上。

使用虚拟环境：

当使用默认的虚拟环境名称时，uv 会自动查找并在后续调用中使用该虚拟环境。

uv venv

# 在新虚拟环境中安装包
uv pip install ruff

“激活”虚拟环境

可以“激活”虚拟环境，以使其包可用：

在 macOS 和 Linux 系统下激活虚拟环境：

source .venv/bin/activate

在 Windows 系统下激活虚拟环境：

.venv\Scripts\activate

“退出”虚拟环境

deactivate

项目实操

以一个小的游戏项目简单演示使用 uv 管理 Python 项目和包。

因为是验证 uv 的使用，所以游戏代码就直接用 DeepSeek 生成一段演示代码。

1. 生成游戏的 Python 脚本

使用 DeepSeek 生成一个模拟超级玛丽游戏的 Python 脚本。因为是简单模拟，提示词就一句话“帮我一个超级玛丽小游戏的Python程序”，生成Python脚本文件命名为：superMario.py，代码如下：

superMario.py

import pygame
import sys

# 初始化Pygame
pygame.init()

# 游戏常量
SCREEN_WIDTH = 800
SCREEN_HEIGHT = 600
GRAVITY = 0.8
JUMP_POWER = -15
PLAYER_SPEED = 5

# 颜色定义
SKY_BLUE = (135, 206, 235)
BROWN = (139, 69, 19)
YELLOW = (255, 255, 0)
RED = (255, 0, 0)
GREEN = (0, 255, 0)

# 初始化屏幕
screen = pygame.display.set_mode((SCREEN_WIDTH, SCREEN_HEIGHT))
pygame.display.set_caption("Super Mario")

clock = pygame.time.Clock()

class Mario(pygame.sprite.Sprite):
    def __init__(self):
        super().__init__()
        self.image = pygame.Surface((30, 40))
        self.image.fill(RED)
        self.rect = self.image.get_rect()
        self.rect.center = (100, SCREEN_HEIGHT - 100)
        self.velocity_y = 0
        self.on_ground = False

    def update(self):
        # 重力
        self.velocity_y += GRAVITY
        self.rect.y += self.velocity_y

        # 地面检测
        if self.rect.bottom >= SCREEN_HEIGHT - 50:
            self.rect.bottom = SCREEN_HEIGHT - 50
            self.on_ground = True
            self.velocity_y = 0

    def jump(self):
        if self.on_ground:
            self.velocity_y = JUMP_POWER
            self.on_ground = False

class Block(pygame.sprite.Sprite):
    def __init__(self, x, y, width, height):
        super().__init__()
        self.image = pygame.Surface((width, height))
        self.image.fill(BROWN)
        self.rect = self.image.get_rect()
        self.rect.x = x
        self.rect.y = y

class Goomba(pygame.sprite.Sprite):
    def __init__(self, x, y):
        super().__init__()
        self.image = pygame.Surface((30, 30))
        self.image.fill(BROWN)
        self.rect = self.image.get_rect()
        self.rect.x = x
        self.rect.y = y
        self.direction = 1
        self.speed = 2

    def update(self):
        self.rect.x += self.speed * self.direction
        # 简单AI - 碰到边缘转向
        if self.rect.right > SCREEN_WIDTH or self.rect.left < 0: self.direction all_sprites='pygame.sprite.Group()' blocks='pygame.sprite.Group()' enemies='pygame.sprite.Group()' for x in range0 screen_width 50: block='Block(x,' screen_height - 50 50 50 blocks.addblock all_sprites.addblock platforms='[' block200 400 100 20 block400 300 100 20 block600 200 100 20 blocks.addplatforms all_sprites.addplatforms goomba='Goomba(500,' screen_height - 80 enemies.addgoomba all_sprites.addgoomba mario='Mario()' all_sprites.addmario def handle_collision: hits='pygame.sprite.spritecollide(mario,' blocks false for hit in hits: if mario.velocity_y> 0:  # 下落时碰撞
            mario.rect.bottom = hit.rect.top
            mario.on_ground = True
            mario.velocity_y = 0
        elif mario.velocity_y < 0:  # 上升时碰撞
            mario.rect.top = hit.rect.bottom
            mario.velocity_y = 0

    # 敌人碰撞检测
    enemy_hits = pygame.sprite.spritecollide(mario, enemies, False)
    for enemy in enemy_hits:
        if mario.rect.bottom < enemy.rect.centery:  # 踩到敌人
            enemy.kill()
            mario.velocity_y = JUMP_POWER/2
        else:  # 侧面碰撞
            game_over()

def game_over():
    pygame.quit()
    sys.exit()

# 游戏主循环
running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        if event.type == pygame.KEYDOWN:
            if event.key == pygame.K_SPACE:
                mario.jump()

    # 获取按键状态
    keys = pygame.key.get_pressed()
    if keys[pygame.K_LEFT]:
        mario.rect.x -= PLAYER_SPEED
    if keys[pygame.K_RIGHT]:
        mario.rect.x += PLAYER_SPEED

    # 更新游戏状态
    all_sprites.update()
    handle_collision()

    # 保持马里奥在屏幕内
    if mario.rect.left < 0: mario.rect.left='0' if mario.rect.right> SCREEN_WIDTH:
        mario.rect.right = SCREEN_WIDTH

    # 绘制画面
    screen.fill(SKY_BLUE)
    all_sprites.draw(screen)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

可见代码用了 pygame 包。

2.创建游戏项目（windows系统）

启动Powrshell终端，输入以下命令创建项目，并进入到项目目录。

uv init game
cd game

3.添加 pygame 包，并同步

uv add pygame
uv sync

4. 将 superMario.py 复制到 game 目录

复制后，目录内容大致如下：

5. 启动虚拟环境，执行游戏脚本

.\.venv\Scripts\activate

python superMario.py

6. 结束游戏，退出虚拟环境

退出虚拟环境命令：

deactivate

环境变量

uv 定义并支持以下环境变量：

持续学习、适应变化、记录点滴、复盘反思、成长进步。