0 简介

在这里插入图片描述

  • 🚀 一个工具替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等
  • ⚡️ 比 pip 快 10-100 倍
  • 🗂️ 提供全面的项目管理功能，包含通用锁文件
  • ❇️ 运行脚本，支持内联依赖元数据
  • 🐍 安装和管理Python 版本
  • 🛠️ 运行和安装 以 Python 包形式发布的工具
  • 🔩 包含 pip 兼容接口，在熟悉 CLI 的同时获得性能提升
  • 🏢 支持 Cargo 风格的工作区用于可扩展项目
  • 💾 磁盘空间高效，通过全局缓存实现依赖去重
  • ⏬ 无需 Rust 或 Python 即可通过 curl 或 pip 安装
  • 🖥️ 支持 macOS、Linux 和 Windows

1 安装方法

1.1 WSL Ubuntu24.04

1.1.1 官方安装

# 两者选其一
curl -LsSf https://astral.sh/uv/install.sh | sh
# -L：跟随重定向
# -s：静默执行模式，将不输出错误和进度信息
# —S：指定只输出错误信息，通常与-s一起使用。
# -f：连接失败时不显示报错

# ------------------------------------------------------------------------
wget -qO- https://astral.sh/uv/install.sh | sh
# -q:启用静默模式,不显示输出信息
# O-:数据不会保存到文件中，而是直接输出到终端或管道。

downloading uv 0.11.0 x86_64-unknown-linux-gnu
no checksums to verify
installing to /home/zhou/.local/bin
  uv
  uvx
everything's installed!

To add $HOME/.local/bin to your PATH, either restart your shell or run:

    source $HOME/.local/bin/env (sh, bash, zsh)
    source $HOME/.local/bin/env.fish (fish)

上述方法会从Github下载相应的文件进行安装，可能需要翻墙操作。如果没有翻墙，有可能会出现无法下载的情况。
UV安装位置：$HOME/.local/bin。
安装完成后要使UV命令生效，需要将安装位置添加到.bashrc文件中。

# 以下两者选其一
# 在.bashrc文件末尾添加如下语句（注意前面的.)
. "$HOME/.local/bin/env"

# 运行source .bashrc命令即可在终端运行uv命令
source ~/.bashrc

1.1.2 从Github下载安装

https://github.com/astral-sh/uv

在这里插入图片描述
在这里插入图片描述
获取下载地址之后，可以通过Github加速网站下载。

# 虾壳
https://xiake.pro/  

# GitHub加速下载
https://iixingchen.github.io/

以uv-x86_64-unknown-linux-gnu.tar.gz为例，通过上述网站获取加速地址。

# Github原始地址：
https://releases.astral.sh/github/uv/releases/download/0.11.0/uv-x86_64-unknown-linux-gnu.tar.gz

# Github加速地址：
https://gitproxy.click/https://releases.astral.sh/github/uv/releases/download/0.11.0/uv-x86_64-unknown-linux-gnu.tar.gz
wget https://gitproxy.click/https://releases.astral.sh/github/uv/releases/download/0.11.0/uv-x86_64-unknown-linux-gnu.tar.gz
curl -O https://gitproxy.click/https://releases.astral.sh/github/uv/releases/download/0.11.0/uv-x86_64-unknown-linux-gnu.tar.gz

将下载的文件解压并复制到/home/zhou/.local/bin（$HOME/.local/bin）目录下，如果没有该目录，手动创建目录后将其复制过去
然后添加以下语句到.bashrc文件。

# 两者选其一
# 在.bashrc文件末尾添加如下语句（注意前面的.)，添加完成后重启终端或运行source .bashrc命令即可在终端运行uv命令
. "$HOME/.local/bin/env"

# 在命令行中运行如下命令（建议），执行完成后重启终端或运行source .bashrc命令即可在终端运行uv命令
source $HOME/.local/bin/env

1.2 Windows安装方法

1.2.1 官方安装

# powershell 终端命令
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Downloading uv 0.11.0 (x86_64-pc-windows-msvc)
Installing to C:\Users\ZHOU\.local\bin
  uv.exe
  uvx.exe
  uvw.exe
everything's installed!

To add C:\Users\ZHOU\.local\bin to your PATH, either restart your shell or run:

    set Path=C:\Users\ZHOU\.local\bin;%Path%   (cmd)
    $env:Path = "C:\Users\ZHOU\.local\bin;$env:Path"   (powershell)

1.1.2 从Github下载安装

https://github.com/astral-sh/uv

在这里插入图片描述

获取下载地址之后，可以通过Github加速网站下载，如果下方地址失效，请自行查询网络更新。

# 虾壳
https://xiake.pro/  

# GitHub加速下载
https://iixingchen.github.io/

# Github Proxy
https://github.akams.cn/

# GitHub加速
https://gh-proxy.com/

以uv-x86_64-pc-windows-msvc.zip为例，通过上述网站获取加速地址。

# Github原始地址：
https://releases.astral.sh/github/uv/releases/download/0.11.0/uv-x86_64-pc-windows-msvc.zip

# Github加速地址：加速地址可能会有变化，建议登录上述网址自己生成相应的加速下载地址
https://gitproxy.click/https://releases.astral.sh/github/uv/releases/download/0.11.0/uv-x86_64-pc-windows-msvc.zip
wget https://gitproxy.click/https://releases.astral.sh/github/uv/releases/download/0.11.0/uv-x86_64-pc-windows-msvc.zip
curl -O https://gitproxy.click/https://releases.astral.sh/github/uv/releases/download/0.11.0/uv-x86_64-pc-windows-msvc.zip

将下载的文件解压并复制到C:\Users\ZHOU\.local\bin目录下，如果没有该目录，手动创建目录后将其复制过去
然后运行如下语句添加到用户变量。

# 在命令行中运行如下命令（建议），执行完成后重启终端运行uv命令
set Path=C:\Users\ZHOU\.local\bin;%Path%           # cmd终端中运行，二者选其一
$env:Path = "C:\Users\ZHOU\.local\bin;$env:Path"   # powershell终端中运行，二者选其一

1.3 验证安装

# 两者选其一
uv --version
uv -V

1.4 uv升级

uv self update

info: Checking for updates...
success: You're on the latest version of uv (v0.9.9)

2 Shell自动补全

2.1 为 uv 命令启用 shell 自动补全

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

# 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'

完成后请重启 shell 或重新加载 shell 配置文件。

2.2 为 uvx 命令启用 shell 自动补全

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

# 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'

完成后请重启 shell 或重新加载 shell 配置文件。

3 配置PyPI仓库为国内源

在 ~/.config/uv/uv.toml（用户级别，建议） 或者 /etc/uv/uv.toml（系统级别） 加入以下语句，两者选择其中一个添加即可。

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true

4 卸载

4.1 WSL Ubuntu24.04

4.1.1 清理缓存数据、删除缓存文件夹

缓存文件及相关文件安装位置

# 缓存目录
uv cache dir
/home/zhou/.cache/uv

# python安装位置
uv python dir
/home/zhou/.local/share/uv/python

# uv tool安装位置
uv tool dir
/home/zhou/.local/share/uv/tools

# 清理缓存
uv cache clean

# 删除缓存文件夹、python和tool文件夹
sudo rm -r "$(uv cache dir)"
sudo rm -r "$(uv python dir)"
sudo rm -r "$(uv tool dir)"

4.1.2 删除uv、uvx二进制文件

# 删除uv、uvx二进制文件
# 两种写法，任选其一即可
sudo rm -rf $HOME/.local/bin/uv
sudo rm -rf $HOME/.local/bin/uvx
# --------------------------------
sudo rm -rf ~/.local/bin/uv
sudo rm -rf ~/.local/bin/uvx

4.1.3 删除uv文件夹

# 这一步直接删除整个文件夹
# 两种写法，任选其一即可
sudo rm -rf $HOME/.local
sudo rm -rf $HOME/.cache
# --------------------------------
sudo rm -rf ~/.local
sudo rm -rf ~/.cache

4.2 Windows

4.2.1 清理缓存数据、删除缓存文件夹

缓存文件及相关文件安装位置

# 缓存目录
uv cache dir
C:\Users\ZHOU\AppData\Local\uv\cache

# python安装位置
uv python dir
C:\Users\ZHOU\AppData\Roaming\uv\python

# uv tool安装位置
uv tool dir
C:\Users\ZHOU\AppData\Roaming\uv\tools

# 清理缓存
uv cache clean

# 删除缓存文件夹、python和tool文件夹
sudo rm -r "$(uv cache dir)"
sudo rm -r "$(uv python dir)"
sudo rm -r "$(uv tool dir)"

4.2.2 删除uv、uvx二进制文件

# 删除uv、uvx二进制文件（powershell）
rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe

rm C:\Users\ZHOU\.local\bin\uv.exe
rm C:\Users\ZHOU\.local\bin\uvx.exe

4.2.3 删除uv文件夹和缓存文件夹

# 这一步直接删除整个文件夹（powershell）
rm $HOME\.local
rm $HOME\Appdata\Roaming\uv
rm $HOME\AppData\Local\uv

rm C:\Users\ZHOU\.local
rm C:\Users\ZHOU\Appdata\Roaming\uv
rm C:\Users\ZHOU\AppData\Local\uv

5 UV使用教程

5.1 Python版本管理（安装和管理Python解释器）

命令说明
uv python list查看可用和已安装的Python 版本
uv python install安装 Python 版本
uv python find查找已安装的 Python信息
uv python pin将当前项目固定使用特定 Python 版本
uv python uninstall卸载 Python 版本
uv python install --reinstall重新安装Python，适用于Python版本的更新

（1）查看可用和已安装的Python 版本

uv python list
cpython-3.15.0a1-linux-x86_64-gnu                 <download available>
cpython-3.15.0a1+freethreaded-linux-x86_64-gnu    <download available>
cpython-3.14.0-linux-x86_64-gnu                   <download available>
cpython-3.14.0+freethreaded-linux-x86_64-gnu      <download available>
cpython-3.13.9-linux-x86_64-gnu                   <download available>
cpython-3.13.9+freethreaded-linux-x86_64-gnu      <download available>
cpython-3.12.12-linux-x86_64-gnu                  <download available>
cpython-3.12.3-linux-x86_64-gnu                   /usr/bin/python3.12
cpython-3.12.3-linux-x86_64-gnu                   /usr/bin/python3 -> python3.12
cpython-3.11.14-linux-x86_64-gnu                  <download available>
cpython-3.10.19-linux-x86_64-gnu                  <download available>
cpython-3.9.25-linux-x86_64-gnu                   <download available>
cpython-3.8.20-linux-x86_64-gnu                   <download available>
pypy-3.11.13-linux-x86_64-gnu                     <download available>
pypy-3.10.16-linux-x86_64-gnu                     <download available>
pypy-3.9.19-linux-x86_64-gnu                      <download available>
pypy-3.8.16-linux-x86_64-gnu                      <download available>
graalpy-3.12.0-linux-x86_64-gnu                   <download available>
graalpy-3.11.0-linux-x86_64-gnu                   <download available>
graalpy-3.10.0-linux-x86_64-gnu                   <download available>
graalpy-3.8.5-linux-x86_64-gnu                    <download available>

（2）查找已安装的 Python 版本

 uv python find
/usr/bin/python3

（3）安装最新版本Python

uv python install 

# 使用此命令会从Github上下载python安装文件，有可能会出现网络无法连接导致下载失败的问题，如果出现以下错误，可以使用下面的命令添加github镜像的方式解决下载的问题
error: Failed to install cpython-3.14.0-linux-x86_64-gnu
  Caused by: Request failed after 3 retries
  Caused by: Failed to download https://github.com/astral-sh/python-build-standalone/releases/download/20251031/cpython-3.14.0%2B20251031-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz
  Caused by: error sending request for url (https://github.com/astral-sh/python-build-standalone/releases/download/20251031/cpython-3.14.0%2B20251031-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz)
  Caused by: client error (Connect)
  Caused by: invalid peer certificate: UnknownIssuer

# Github加速下载
uv python install --mirror https://gh.llkk.cc/https://github.com/astral-sh/python-build-standalone/releases/download

Installed Python 3.14.0 in 6.23s
 + cpython-3.14.0-linux-x86_64-gnu (python3.14)

# Github镜像加速地址，如果下方地址失效，请自行查询网络更新
# 虾壳
https://xiake.pro/  

# GitHub加速下载
https://iixingchen.github.io/

# Github Proxy
https://github.akams.cn/

# GitHub加速
https://gh-proxy.com/

（4）安装指定版本Python

uv python install 3.13  --mirror https://gh.llkk.cc/https://github.com/astral-sh/python-build-standalone/releases/download

Installed Python 3.13.9 in 5.24s
 + cpython-3.13.9-linux-x86_64-gnu (python3.13)

在这里插入图片描述

（5）安装多个版本Python

uv python install 3.11 3.12 --mirror https://gh.llkk.cc/https://github.com/astral-sh/python-build-standalone/releases/download

Installed 2 versions in 6.59s
 + cpython-3.11.14-linux-x86_64-gnu (python3.11)
 + cpython-3.12.12-linux-x86_64-gnu (python3.12)

（6）安装其它实现的Python

# Pypy版本的Python已经设置Pypi仓库的国内源，因此不需要再添加Github的国内镜像加速
uv python install pypy@3.11

Installed Python 3.11.13 in 7.35s
 + pypy-3.11.13-linux-x86_64-gnu

uv python install graalpy@3.12 --mirror https://gh.llkk.cc/https://github.com/astral-sh/python-build-standalone/releases/download

Installed Python 3.12.0 in 18.59s
 + graalpy-3.12.0-linux-x86_64-gnu

在这里插入图片描述

（7）查看已安装的Python版本

uv python find
/home/zhou/.local/share/uv/python/cpython-3.14.0-linux-x86_64-gnu/bin/python3.14

uv python find 3.12
/home/zhou/.local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/bin/python3.12

（8）将当前项目固定使用特定 Python 版本
在具体的某个项目中，进入项目目录后使用如下命令指定选用的python版本

uv python pin 3.14

Pinned `.python-version` to `3.14`

此命令会在指定目录下创建一个.python-version文件，记录Python版本号，此处选用的python版本只和uv管理的虚拟环境有关系，和全局的python、python3命令都没有关系。

3.14

以后如果不在需要这个文件，直接删除.python-version文件即可。
（9）卸载指定的Python版本

uv pyhon list

cpython-3.15.0a1-linux-x86_64-gnu                 <download available>
cpython-3.15.0a1+freethreaded-linux-x86_64-gnu    <download available>
cpython-3.14.0-linux-x86_64-gnu                   .local/bin/python3.14 -> .local/share/uv/python/cpython-3.14.0-linux-x86_64-gnu/bin/python3.14
cpython-3.14.0-linux-x86_64-gnu                   .local/share/uv/python/cpython-3.14.0-linux-x86_64-gnu/bin/python3.14
cpython-3.14.0+freethreaded-linux-x86_64-gnu      <download available>
cpython-3.13.9-linux-x86_64-gnu                   .local/bin/python3.13 -> .local/share/uv/python/cpython-3.13.9-linux-x86_64-gnu/bin/python3.13
cpython-3.13.9-linux-x86_64-gnu                   .local/share/uv/python/cpython-3.13.9-linux-x86_64-gnu/bin/python3.13
cpython-3.13.9+freethreaded-linux-x86_64-gnu      <download available>
cpython-3.12.12-linux-x86_64-gnu                  .local/bin/python3.12 -> .local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/bin/python3.12
cpython-3.12.12-linux-x86_64-gnu                  .local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/bin/python3.12
cpython-3.12.3-linux-x86_64-gnu                   /usr/bin/python3.12
cpython-3.12.3-linux-x86_64-gnu                   /usr/bin/python3 -> python3.12
cpython-3.11.14-linux-x86_64-gnu                  .local/bin/python3.11 -> .local/share/uv/python/cpython-3.11.14-linux-x86_64-gnu/bin/python3.11
cpython-3.11.14-linux-x86_64-gnu                  .local/share/uv/python/cpython-3.11.14-linux-x86_64-gnu/bin/python3.11
cpython-3.10.19-linux-x86_64-gnu                  <download available>
cpython-3.9.25-linux-x86_64-gnu                   <download available>
cpython-3.8.20-linux-x86_64-gnu                   <download available>
pypy-3.11.13-linux-x86_64-gnu                     .local/share/uv/python/pypy-3.11.13-linux-x86_64-gnu/bin/pypy3.11
pypy-3.10.16-linux-x86_64-gnu                     <download available>
pypy-3.9.19-linux-x86_64-gnu                      <download available>
pypy-3.8.16-linux-x86_64-gnu                      <download available>
graalpy-3.12.8-linux-x86_64-gnu                   .local/share/uv/python/graalpy-3.12.0-linux-x86_64-gnu/bin/graalpy
graalpy-3.11.0-linux-x86_64-gnu                   <download available>
graalpy-3.10.0-linux-x86_64-gnu                   <download available>
graalpy-3.8.5-linux-x86_64-gnu                    <download available>

uv python uninstall 3.12

Searching for Python versions matching: Python 3.12
Uninstalled 2 versions in 3.62s
 - graalpy-3.12.0-linux-x86_64-gnu
 - cpython-3.12.12-linux-x86_64-gnu (python3.12)

uv python uninstall 3.13 3.14

Searching for Python versions matching: Python 3.13
Searching for Python versions matching: Python 3.14
Uninstalled 2 versions in 3.29s
 - cpython-3.13.9-linux-x86_64-gnu (python3.13)
 - cpython-3.14.0-linux-x86_64-gnu (python3.14)

（10）重新安装Python

uv python install --reinstall --mirror https://gh.llkk.cc/https://github.com/astral-sh/python-build-standalone/releases/download

Installed 2 versions in 7.51s
 ~ cpython-3.13.9-linux-x86_64-gnu (python3.13)
 ~ cpython-3.14.0-linux-x86_64-gnu (python3.14)

在这里插入图片描述

5.2 项目管理（创建和开发带有 pyproject.toml的Python 项目）

命令说明
uv init创建新 Python 项目并初始化该项目
uv add为项目添加依赖，安装软件包并将依赖声明写入pyproject.toml文件
uv remove从项目移除依赖，移除软件包并将依赖从文件pyproject.toml中移除
uv sync同步项目依赖到环境
uv lock为项目依赖创建锁文件
uv run在项目环境中运行命令
uv export将项目的锁文件导出为其他格式
uv tree查看项目依赖树
uv build构建项目为分发包
uv publish发布项目到包索引

（1）创建新Python项目

# 方法一：从终端中导航到要创建项目的目录位置，运行如下命令创建新的项目文件夹并在此文件夹下添加Python项目
 pwd 
/home/zhou/code

# uv init不指定使用的Python版本，默认使用已安装的最新版本，且使用的Python版本信息存储在.python-version文件中
uv init test1
Initialized project `test` at `/home/zhou/code/test1`

# 方法二：首先从终端导航到要创建项目的目录位置，手动先创建项目文件夹，cd进入创建的项目文件夹，运行命令创建新的Python项目
pwd
/home/zhou/code

mkdir test2
cd test2

# uv init不指定使用的Python版本，默认使用已安装的最新版本，且使用的Python版本信息存储在.python-version文件中
uv init
Initialized project `test2`

创建的文件结构如下：

tree
.
├── README.md
├── main.py
└── pyproject.toml

1 directory, 3 files

main.py 文件包含一个简单的 “Hello world” 程序。

# 项目初始化时指定需要使用的Python版本，且使用的Python版本信息存储在.python-version文件中
 uv init test --python 3.13
 
Initialized project `test` at `/home/zhou/code/test`


cat .python-version
3.13

（2）创建虚拟环境
.venv 文件夹包含项目的虚拟环境，是与系统其他部分隔离的 Python 环境。uv 将在此处安装项目的依赖项。

# 如果不指定虚拟环境的Python版本，默认会使用最新的已安装版本
uv venv

Using CPython 3.14.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

# 创建指定Python版本的虚拟环境
uv venv --python 3.13

Using CPython 3.13.9
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

# 激活虚拟环境
source .venv/bin/activate
(test) zhou@ZHOU-PC:~/code/test$

# 取消激活的虚拟环境
deactivate
zhou@ZHOU-PC:~/code/test$

注意事项：如果项目虚拟化时.python-version文件中指定的Python版本与创建虚拟环境时指定的Python版本不一致，会出现提示。建议的操作步骤，首先更改
.python-version文件中Python版本，通过uv sync命令删除旧虚拟环境并重新创建新的虚拟环境。

uv sync

Using CPython 3.14.0
Removed virtual environment at: .venv
Creating virtual environment at: .venv
Resolved 1 package in 2ms
Audited in 0.00ms

（3）为项目添加依赖

uv add pandas

Using CPython 3.14.0
Creating virtual environment at: .venv
Resolved 7 packages in 1.19s
Prepared 6 packages in 2.88s
Installed 6 packages in 36ms
 + numpy==2.3.4
 + pandas==2.3.3
 + python-dateutil==2.9.0.post0
 + pytz==2025.2
 + six==1.17.0
 + tzdata==2025.2

在这里插入图片描述

此命令会首先寻找.venv虚拟环境，如果没有先创建.venv虚拟环境，然后在pyproject.toml文件中添加依赖项记录。

cat pyproject.toml

[project]
name = "test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.14"
dependencies = [
    "pandas>=2.3.3",
]

（4）从项目移除依赖

uv remove pandas

Resolved 1 package in 3ms
Uninstalled 6 packages in 33ms
 - numpy==2.3.4
 - pandas==2.3.3
 - python-dateutil==2.9.0.post0
 - pytz==2025.2
 - six==1.17.0
 - tzdata==2025.2

此命令会从pyproject.toml文件中删除依赖项记录。

 cat pyproject.toml
 
[project]
name = "test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.14"
dependencies = []

（5）将项目的锁文件导出为其他格式
目前支持 requirements.txt 和 pylock.toml（PEP 751）格式。

uv export requirements.txt

从requirements.txt文件恢复所有依赖项

uv add -r requirements.txt [-c constraints.txt]

（5）同步项目依赖到环境

uv sync

Resolved 1 package in 0.88ms
Audited in 0.00ms

（6）为项目依赖创建锁文件
uv.lock 是一个跨平台的锁定文件，其中包含有关项目依赖项的确切信息。与用于指定项目大致要求的 pyproject.toml 不同，锁定文件包含安装在项目环境中的确切解析版本所有信息。此文件应提交到版本控制系统，以便在不同机器上实现一致且可重现的安装。

uv.lock 是一个人类可读的 TOML 文件，但由 uv 管理，不应手动编辑。

uv lock

Resolved 7 packages in 0.91ms

（7）在项目环境中运行命令

# 运行指定的脚本文件
uv run bash scripts/foo.sh

（8）查看项目依赖树

uv tree
 
Resolved 7 packages in 0.88ms
test v0.1.0
└── pandas v2.3.3
    ├── numpy v2.3.4
    ├── python-dateutil v2.9.0.post0
    │   └── six v1.17.0
    ├── pytz v2025.2
    └── tzdata v2025.2

（9）构建项目为分发包
uv build 可用于为项目构建源发行版和二进制发行版。默认情况下，uv build 将在当前目录中构建项目，并将构建的工件放置在 dist/ 子目录中。

uv build

Building source distribution...
running egg_info
creating test.egg-info
writing test.egg-info/PKG-INFO
writing dependency_links to test.egg-info/dependency_links.txt
writing requirements to test.egg-info/requires.txt
writing top-level names to test.egg-info/top_level.txt
writing manifest file 'test.egg-info/SOURCES.txt'
reading manifest file 'test.egg-info/SOURCES.txt'
writing manifest file 'test.egg-info/SOURCES.txt'
running sdist
running egg_info
writing test.egg-info/PKG-INFO
writing dependency_links to test.egg-info/dependency_links.txt
writing requirements to test.egg-info/requires.txt
writing top-level names to test.egg-info/top_level.txt
reading manifest file 'test.egg-info/SOURCES.txt'
writing manifest file 'test.egg-info/SOURCES.txt'
running check
creating test-0.1.0
creating test-0.1.0/test.egg-info
copying files to test-0.1.0...
copying README.md -> test-0.1.0
copying main.py -> test-0.1.0
copying pyproject.toml -> test-0.1.0
copying test.egg-info/PKG-INFO -> test-0.1.0/test.egg-info
copying test.egg-info/SOURCES.txt -> test-0.1.0/test.egg-info
copying test.egg-info/dependency_links.txt -> test-0.1.0/test.egg-info
copying test.egg-info/requires.txt -> test-0.1.0/test.egg-info
copying test.egg-info/top_level.txt -> test-0.1.0/test.egg-info
copying test.egg-info/SOURCES.txt -> test-0.1.0/test.egg-info
Writing test-0.1.0/setup.cfg
Creating tar archive
removing 'test-0.1.0' (and everything under it)
Building wheel from source distribution...
running egg_info
writing test.egg-info/PKG-INFO
writing dependency_links to test.egg-info/dependency_links.txt
writing requirements to test.egg-info/requires.txt
writing top-level names to test.egg-info/top_level.txt
reading manifest file 'test.egg-info/SOURCES.txt'
writing manifest file 'test.egg-info/SOURCES.txt'
running bdist_wheel
running build
running build_py
creating build/lib
copying main.py -> build/lib
running egg_info
writing test.egg-info/PKG-INFO
writing dependency_links to test.egg-info/dependency_links.txt
writing requirements to test.egg-info/requires.txt
writing top-level names to test.egg-info/top_level.txt
reading manifest file 'test.egg-info/SOURCES.txt'
writing manifest file 'test.egg-info/SOURCES.txt'
installing to build/bdist.linux-x86_64/wheel
running install
running install_lib
creating build/bdist.linux-x86_64/wheel
copying build/lib/main.py -> build/bdist.linux-x86_64/wheel/.
running install_egg_info
Copying test.egg-info to build/bdist.linux-x86_64/wheel/./test-0.1.0-py3.14.egg-info
running install_scripts
creating build/bdist.linux-x86_64/wheel/test-0.1.0.dist-info/WHEEL
creating '/home/zhou/code/test/dist/.tmp-nv0nva7c/test-0.1.0-py3-none-any.whl' and adding 'build/bdist.linux-x86_64/wheel' to it
adding 'main.py'
adding 'test-0.1.0.dist-info/METADATA'
adding 'test-0.1.0.dist-info/WHEEL'
adding 'test-0.1.0.dist-info/top_level.txt'
adding 'test-0.1.0.dist-info/RECORD'
removing build/bdist.linux-x86_64/wheel
Successfully built dist/test-0.1.0.tar.gz
Successfully built dist/test-0.1.0-py3-none-any.whl

（10）发布项目到包索引（较少使用）

uv publish

Publishing 2 files to https://upload.pypi.org/legacy/

5.3 脚本运行（执行独立的 Python 脚本）

命令说明
uv run运行脚本
uv add --script为脚本添加依赖
uv remove --script从脚本移除依赖

Python 脚本是用于独立执行的文件，例如使用 python <script>.py 命令。
（1）运行指定的脚本文件

uv run bash scripts/foo.sh

（2）运行无依赖的python脚本

uv run example.py

（3）运行带有依赖项的脚本

uv run --no-project example.py

（4）创建Python脚本

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

（5）锁定依赖项

uv lock --script example.py

5.4 使用工具（运行和安装发布到 Python 包索引的工具）

命令说明
uvx / uv tool run在临时环境中运行工具
uv tool install为用户以全局方式安装工具
uv tool uninstall卸载已安装工具
uv tool list列出已安装的工具
uv tool upgrade更新指定的工具
uv tool update-shell更新 shell 以包含工具可执行文件

（1）在临时环境中运行工具（工具未安装）

# 以下两条命令完全等效，二者选其一即可
uvx pycowsay hello from uv
uv tool run pycowsay hello

  -----
< hello >
  -----
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

（2）为用户以全局方式安装工具

uv tool install  pycowsay

Resolved 1 package in 2ms
Installed 1 package in 23ms
 + pycowsay==0.0.0.2
Installed 1 executable: pycowsay

（3）列出已安装的工具

uv tool list

pycowsay v0.0.0.2
- pycowsay

（4）卸载已安装的工具

uv tool uninstall pycowsay

Uninstalled 1 executable: pycowsay

（5）更新指定的工具

uv tool upgrade pycowsay

Nothing to upgrade

（6）更新 shell 以包含工具可执行文件

uv tool update-shell

Executable directory /home/zhou/.local/bin is already in PATH

5.5 pip接口（手动管理环境和包）

pip接口适用于遗留工作流或高级命令无法提供足够控制的情况
（1）创建虚拟环境（替代 venv 和 virtualenv）

命令说明
uv venv创建新的虚拟环境
① 创建虚拟环境
# 创建.venv虚拟环境，Python使用默认版本（.python-version记录Python版本）
uv venv

Using CPython 3.14.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

# 创建vm虚拟环境，Python使用默认版本（.python-version记录Python版本）
uv venv vm

Using CPython 3.14.0
Creating virtual environment at: vm
Activate with: source vm/bin/activate

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

Using CPython 3.13.9
warning: The requested interpreter resolved to Python 3.13.9, which is incompatible with the project's Python requirement: `>=3.14` (from `project.requires-python`)
Creating virtual environment at: .venv
✔ A virtual environment already exists at `.venv`. Do you want to replace it? · yes
Activate with: source .venv/bin/activate

ls -la

total 36
drwxr-xr-x 5 zhou zhou 4096 Nov 14 14:48 .
drwxr-xr-x 3 zhou zhou 4096 Nov 14 14:47 ..
drwxr-xr-x 7 zhou zhou 4096 Nov 14 14:45 .git
-rw-r--r-- 1 zhou zhou  109 Nov 14 14:45 .gitignore
-rw-r--r-- 1 zhou zhou    5 Nov 14 14:45 .python-version
drwxr-xr-x 4 zhou zhou 4096 Nov 14 14:48 .venv
-rw-r--r-- 1 zhou zhou    0 Nov 14 14:45 README.md
-rw-r--r-- 1 zhou zhou   82 Nov 14 14:45 main.py
-rw-r--r-- 1 zhou zhou  150 Nov 14 14:45 pyproject.toml
drwxr-xr-x 4 zhou zhou 4096 Nov 14 14:48 vm

② 激活虚拟环境

# Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

③ 停用虚拟环境

deactivate

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

命令说明
uv pip install将包安装到当前环境
uv pip show显示已安装包的详细信息
uv pip freeze列出已安装包及其版本
uv pip check检查当前环境的包兼容性
uv pip list列出已安装包
uv pip tree查看环境的依赖树
uv pip uninstall卸载包

① 安装单个包到当前环境

uv pip install flask

Resolved 7 packages in 1.06s
Prepared 7 packages in 275ms
Installed 7 packages in 6ms
 + blinker==1.9.0
 + click==8.3.0
 + flask==3.1.2
 + itsdangerous==2.2.0
 + jinja2==3.1.6
 + markupsafe==3.0.3
 + werkzeug==3.1.3

② 安装多个包到当前环境

uv pip install flask fastapi

Resolved 18 packages in 3.07s
Prepared 11 packages in 412ms
Installed 18 packages in 44ms
 + annotated-doc==0.0.4
 + annotated-types==0.7.0
 + anyio==4.11.0
 + blinker==1.9.0
 + click==8.3.0
 + fastapi==0.121.2
 + flask==3.1.2
 + idna==3.11
 + itsdangerous==2.2.0
 + jinja2==3.1.6
 + markupsafe==3.0.3
 + pydantic==2.12.4
 + pydantic-core==2.41.5
 + sniffio==1.3.1
 + starlette==0.49.3
 + typing-extensions==4.15.0
 + typing-inspection==0.4.2
 + werkzeug==3.1.**3**

③ 安装指定版本的包到当前环境

uv pip install django==5.1

Resolved 3 packages in 1.49s
Prepared 3 packages in 1.41s
Installed 3 packages in 329ms
 + asgiref==3.10.0
 + django==5.1
 + sqlparse==0.5.3


uv pip install django>=5.2.2

Resolved 3 packages in 1.22s
Prepared 1 package in 1.27s
Installed 3 packages in 288ms
 + asgiref==3.10.0
 + django==5.2.8
 + sqlparse==0.5.3

④ 显示已安装的包信息（指定单个或多个包名称）

uv pip show flask

Name: flask
Version: 3.1.2
Location: /home/zhou/code/test/.venv/lib/python3.14/site-packages
Requires: blinker, click, itsdangerous, jinja2, markupsafe, werkzeug
Required-by:

uv pip show django fastapi

Name: django
Version: 5.2.8
Location: /home/zhou/code/test/.venv/lib/python3.14/site-packages
Requires: asgiref, sqlparse
Required-by:
---
Name: fastapi
Version: 0.121.2
Location: /home/zhou/code/test/.venv/lib/python3.14/site-packages
Requires: annotated-doc, pydantic, starlette, typing-extensions
Required-by:

⑤ 列出已安装包及其版本

uv pip freeze

annotated-doc==0.0.4
annotated-types==0.7.0
anyio==4.11.0
asgiref==3.10.0
blinker==1.9.0
click==8.3.0
django==5.2.8
fastapi==0.121.2
flask==3.1.2
idna==3.11
itsdangerous==2.2.0
jinja2==3.1.6
markupsafe==3.0.3
pandas==2.3.3
pydantic==2.12.4
pydantic-core==2.41.5
sniffio==1.3.1
sqlparse==0.5.3
starlette==0.49.3
typing-extensions==4.15.0
typing-inspection==0.4.2
werkzeug==3.1.3

⑥ 检查当前环境的包兼容性

uv pip check

Checked 22 packages in 0.78ms
Found 4 incompatibilities
The package `pandas` requires `numpy>=1.26.0 ; python_full_version >= '3.12'`, but it's not installed
The package `pandas` requires `python-dateutil>=2.8.2`, but it's not installed
The package `pandas` requires `pytz>=2020.1`, but it's not installed
The package `pandas` requires `tzdata>=2022.7`, but it's not installed

⑦ 列出已安装包

uv pip list

Package           Version
----------------- -------
annotated-doc     0.0.4
annotated-types   0.7.0
anyio             4.11.0
asgiref           3.10.0
blinker           1.9.0
click             8.3.0
django            5.2.8
fastapi           0.121.2
flask             3.1.2
idna              3.11
itsdangerous      2.2.0
jinja2            3.1.6
markupsafe        3.0.3
pandas            2.3.3
pydantic          2.12.4
pydantic-core     2.41.5
sniffio           1.3.1
sqlparse          0.5.3
starlette         0.49.3
typing-extensions 4.15.0
typing-inspection 0.4.2
werkzeug          3.1.3

⑧ 查看环境的依赖树

uv pip tree

django v5.2.8
├── asgiref v3.10.0
└── sqlparse v0.5.3
fastapi v0.121.2
├── annotated-doc v0.0.4
├── pydantic v2.12.4
│   ├── annotated-types v0.7.0
│   ├── pydantic-core v2.41.5
│   │   └── typing-extensions v4.15.0
│   ├── typing-extensions v4.15.0
│   └── typing-inspection v0.4.2
│       └── typing-extensions v4.15.0
├── starlette v0.49.3
│   └── anyio v4.11.0
│       ├── idna v3.11
│       └── sniffio v1.3.1
└── typing-extensions v4.15.0
flask v3.1.2
├── blinker v1.9.0
├── click v8.3.0
├── itsdangerous v2.2.0
├── jinja2 v3.1.6
│   └── markupsafe v3.0.3
├── markupsafe v3.0.3
└── werkzeug v3.1.3
    └── markupsafe v3.0.3
pandas v2.3.3

⑨ 卸载包

v pip uninstall django

Uninstalled 1 package in 97ms
 - django==5.2.8

uv pip uninstall flask fastapi

Uninstalled 2 packages in 2ms
 - fastapi==0.121.2
 - flask==3.1.2

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

命令说明
uv pip compile将需求编译为锁定文件
uv pip sync根据锁定文件同步环境
① 锁定 pyproject.toml 中声明的依赖项，该命令会生成requirements.txt文件
uv pip compile pyproject.toml -o requirements.txt

Resolved 6 packages in 1.16s
# This file was autogenerated by uv via the following command:
#    uv pip compile pyproject.toml -o requirements.txt
numpy==2.3.4
    # via pandas
pandas==2.3.3
    # via test (pyproject.toml)
python-dateutil==2.9.0.post0
    # via pandas
pytz==2025.2
    # via pandas
six==1.17.0
    # via python-dateutil
tzdata==2025.2
    # via pandas

② 根据锁定文件同步环境

# 此命令会根据requirements.txt中记录的软件程序更新虚拟环境，在requirements.txt中记录的包会被安装，不在requirements.txt中记录的包会被删除
# 除了requirements.txt文件外，也可以使用pyproject.toml文件
uv pip sync requirements.txt

Resolved 6 packages in 4ms
Uninstalled 8 packages in 11ms
 - contourpy==1.3.3
 - cycler==0.12.1
 - fonttools==4.60.1
 - kiwisolver==1.4.9
 - matplotlib==3.10.7
 - packaging==25.0
 - pillow==12.0.0
 - pyparsing==3.2.5

# -----------------------------------
uv pip sync pyproject.toml

Resolved 1 package in 3ms
Uninstalled 13 packages in 30ms
 - contourpy==1.3.3
 - cycler==0.12.1
 - fonttools==4.60.1
 - kiwisolver==1.4.9
 - matplotlib==3.10.7
 - numpy==2.3.4
 - packaging==25.0
 - pillow==12.0.0
 - pyparsing==3.2.5
 - python-dateutil==2.9.0.post0
 - pytz==2025.2
 - six==1.17.0
 - tzdata==2025.2

5.6 实用工具（管理和检查 uv 的状态）

管理和检查 uv 的状态，例如缓存、存储目录或执行自我更新。

命令说明
uv cache clean清除缓存
uv cache prune清除过期缓存
uv cache dir显示 uv 缓存目录路径
uv tool dir显示 uv 工具目录路径
uv python dir显示 uv 安装的 Python 版本路径
uv self update将 uv 更新至最新版本

（1）显示uv缓存目录路径

uv cache dir 
/home/zhou/.cache/uv

zhou@ZHOU-PC:~/.cache/uv$ ls -la
total 44
drwxr-xr-x  9 zhou zhou 4096 Nov 14 15:26 .
drwx------  3 zhou zhou 4096 Nov 14 11:21 ..
-rw-r--r--  1 zhou zhou    1 Nov 14 11:21 .gitignore
-rwxrwxrwx  1 zhou zhou    0 Nov 14 11:21 .lock
-rw-r--r--  1 zhou zhou   43 Nov 14 11:21 CACHEDIR.TAG
drwxr-xr-x 41 zhou zhou 4096 Nov 14 15:26 archive-v0
drwxr-xr-x  2 zhou zhou 4096 Nov 14 11:21 builds-v0
drwxr-xr-x  3 zhou zhou 4096 Nov 14 11:21 environments-v2
drwxr-xr-x  3 zhou zhou 4096 Nov 14 11:21 interpreter-v4
drwxr-xr-x  2 zhou zhou 4096 Nov 14 11:21 sdists-v9
drwxr-xr-x  3 zhou zhou 4096 Nov 14 11:21 simple-v18
drwxr-xr-x  3 zhou zhou 4096 Nov 14 11:21 wheels-v5

（2）显示 uv 安装的 Python 版本路径

uv python dir
/home/zhou/.local/share/uv/python

zhou@ZHOU-PC:~/.local/share/uv/python$ ls -la
total 24
drwxr-xr-x 5 zhou zhou 4096 Nov 14 10:05 .
drwxr-xr-x 4 zhou zhou 4096 Nov 14 11:33 ..
-rw-r--r-- 1 zhou zhou    1 Nov 14 09:19 .gitignore
-rwxrwxrwx 1 zhou zhou    0 Nov 14 09:19 .lock
drwxr-xr-x 9 zhou zhou 4096 Nov 14 10:05 .temp
drwxr-xr-x 6 zhou zhou 4096 Nov 14 10:05 cpython-3.13.9-linux-x86_64-gnu
drwxr-xr-x 6 zhou zhou 4096 Nov 14 10:05 cpython-3.14.0-linux-x86_64-gnu

（3）显示 uv 工具目录路径

uv tool dir
/home/zhou/.local/share/uv/tools

zhou@ZHOU-PC:~/.local/share/uv/tools$ ls -la
total 16
drwxr-xr-x 3 zhou zhou 4096 Nov 14 11:33 .
drwxr-xr-x 4 zhou zhou 4096 Nov 14 11:33 ..
-rw-r--r-- 1 zhou zhou    1 Nov 14 11:33 .gitignore
-rwxrwxrwx 1 zhou zhou    0 Nov 14 11:33 .lock
drwxr-xr-x 5 zhou zhou 4096 Nov 14 11:33 pycowsay

（4）清除缓存

uv cache clean

Clearing cache at: /home/zhou/.cache/uv
Removed 13403 files (248.4MiB)

（5）清除过期缓存

uv cache prune
No cache found at: /home/zhou/.cache/uv

（6）将 uv 更新至最新版本

uv self update

info: Checking for updates...
success: You're on the latest version of uv (v0.9.9)

6 项目结构和文件

一个项目由几个重要部分组成，它们协同工作，使 uv 能够管理你的项目。 除了 uv init 创建的文件外，在你首次运行项目命令（如 uv run、uv sync 或 uv lock）时，uv 还会在项目根目录中创建一个虚拟环境和 uv.lock 文件。

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

6.1 pyproject.toml

pyproject.toml 包含项目的元数据：

[project]
name = "test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.14"
dependencies = []

6.2 .python-version

.python-version 文件包含项目的默认 Python 版本。记录uv 在创建项目的虚拟环境时使用的 Python 版本。

3.14

6.3 .venv

.venv 文件夹包含项目的虚拟环境，是与系统其他部分隔离的 Python 环境。uv 将在此处安装项目的依赖项。此处需要的Python版本记录在.python-version 文件中。

.
├── CACHEDIR.TAG
├── bin
│   ├── activate
│   ├── activate.bat
│   ├── activate.csh
│   ├── activate.fish
│   ├── activate.nu
│   ├── activate.ps1
│   ├── activate_this.py
│   ├── deactivate.bat
│   ├── pydoc.bat
│   ├── python -> /home/zhou/.local/share/uv/python/cpython-3.14.0-linux-x86_64-gnu/bin/python3.14
│   ├── python3 -> python
│   └── python3.14 -> python
├── lib
│   └── python3.14
│       └── site-packages
│           ├── __pycache__
│           │   └── _virtualenv.cpython-314.pyc
│           ├── _virtualenv.pth
│           └── _virtualenv.py
├── lib64 -> lib
├── pyvenv.cfg
└── share
    └── man
        └── man1

10 directories, 17 files

6.4 uv.lock

uv.lock 是一个跨平台的锁定文件，其中包含有关项目依赖项的确切信息。与用于指定项目大致要求的 pyproject.toml 不同，锁定文件包含安装在项目环境中的确切解析版本。此文件应提交到版本控制系统，以便在不同机器上实现一致且可重现的安装。
uv.lock 是一个人类可读的 TOML 文件，但由 uv 管理，不应手动编辑。

uv lock
Resolved 1 package in 0.70ms

version = 1
revision = 3
requires-python = ">=3.14"

[[package]]
name = "test"
version = "0.1.0"
source = { virtual = "." }

7 uv配置文件

uv的配置文件分为项目级别配置文件、用户级别配置文件和系统级别配置文件。当前项目目录下的pyproject.toml为项目级别配置文件，~/.config/uv/uv.toml 为用户级别配置文件，/etc/uv/uv.toml为系统级别配置。
（1）在项目中，uv 将从项目根目录开始搜索，如果找到 pyproject.toml 文件，uv 将从 [tool.uv] 表中读取配置。如果不存在这样的表，pyproject.toml 文件将被忽略，uv 将继续在其它目录层级结构中搜索。

# pyproject.toml

[[tool.uv.index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true

（2）uv 还会搜索 uv.toml 文件（用户级别和系统级别配置必须使用 uv.toml 格式），uv 会在 macOS 和 Linux 系统上的 ~/.config/uv/uv.toml（或 $XDG_CONFIG_HOME/uv/uv.toml），或 Windows 系统上的 %APPDATA%\uv\uv.toml 中查找用户级配置；在 macOS 和 Linux 系统上的 /etc/uv/uv.toml（或 $XDG_CONFIG_DIRS/uv/uv.toml），或 Windows 系统上的 %SYSTEMDRIVE%\ProgramData\uv\uv.toml 中查找系统级配置。

# uv.toml

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true

（3）如果同一个目录中同时存在 uv.toml 和 pyproject.toml 文件，uv.toml 文件优先于 pyproject.toml 文件，将从 uv.toml 中读取配置，而 pyproject.toml 中的 [tool.uv] 部分将被忽略。
（4）如果同时找到项目级、用户级和系统级配置文件（位于不同的目录中），设置将被合并，项目级配置优先于用户级配置，用户级配置优先于系统级配置。

# uv
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

玩转 AtomCode！AtomGit「码动四季・开源同行」夏季征稿获奖名单出炉！

avatar AtomGit开源社区
cover

上海AI实验室 Intern Lumina U2 上线 AtomGit AI，昇腾千卡训练提效 1.85 倍

avatar AtomGit开源社区
cover

本周 G-Star 开源项目推荐

avatar AtomGit开源社区