uv 是一个用 Rust 编写的、速度极快的 Python 包和项目管理工具，由 ruff 的作者开发。它的目标是成为 pip、venv、virtualenv 和 pip-tools 等工具的直接替代品，提供一个统一、快速且易于使用的体验。
本文总结了如何安装和使用 uv。
官方仓库：
uv使用
一、简介
如果你对 Python 的包管理生态有所了解，你可能用过 pip 来安装包，用 venv 或 virtualenv 来创建虚拟环境，用 pip-tools 来锁定依赖。这些工具各司其职，但组合使用起来有时会显得有些繁琐。
uv 的出现就是为了解决这个问题。它将包安装、虚拟环境管理和依赖解析等功能集成到了一个单一的命令行工具中，并且性能极高。
主要特点：
- 极速：
uv利用了先进的依赖解析算法和全局缓存，安装和解析包的速度比pip快得多。 - 一体化： 无需在
pip和venv之间切换，uv提供了统一的命令来处理大多数包和环境管理任务。 - 直接替代：
uv的命令设计与pip非常相似（例如uv pip install），使得迁移成本非常低。 - 依赖锁定： 内置了类似
pip-tools的功能，可以从pyproject.toml或requirements.in文件编译生成锁定的requirements.txt文件。
二、安装
uv 提供了多种安装方式：
macOS 和 Linux
使用 curl:
curl -LsSf https://astral.sh/uv/install.sh | shWindows
使用 PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"其他方式
也可以通过 pip、brew 等包管理器安装：
# 通过 pip
pip install uv
# 通过 Homebrew
brew install uv安装完成后，可以通过 uv --version 来验证是否成功。
三、基本使用
uv 的使用非常直观，特别是对于熟悉 pip 和 venv 的用户。
1、管理python版本
使用如下命令，显示出当前环境中所有可用的python版本（包括已经安装的和可以安装的）
uv python list如果需要安装其他版本的python，使用如下命令
uv python install 3.12除了标准python之外，还可以安装其他的Python实现，比如PyPy实现的python：
uv python install pypy@3.10查找某个python版本的路径：
❯ uv python find 3.10
/Library/Frameworks/Python.framework/Versions/3.10/bin/python3.10四、单个脚本使用
参考：
uv 可以管理单文件脚本的依赖项和环境；
例如：创建一个新脚本并添加内联元数据来声明其依赖项：
$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
$ uv add --script example.py requests
Updated `example.py`然后，在隔离的虚拟环境中运行脚本：
$ uv run example.py
Reading inline script metadata from: example.py
Installed 5 packages in 12ms
<Response [200]>五、项目中使用
1、选用python版本
在具体的某个项目中，进入项目目录，使用如下命令指定选用的python版本：
uv python pin 版本号这个命令会在指定目录下创建一个.python-version文件，内容如下：
❯ uv python pin 3.10
Pinned `.python-version` to `3.10`
❯ cat .python-version
3.10注意：这里选用的python版本只和uv管理的虚拟环境有关系，和我们全局的python、python3命令都没有关系！
2、创建虚拟环境
创建项目有两种方式，第一种方式，先创建好项目目录，然后设置python版本并初始化uv虚拟环境：
uv python pin 3.10
uv init # 初始化执行了uv init之后，会在当前目录下创建几个文件，同时也会在当前目录下执行git init创建出一个新的git仓库来：
❯ uv python pin 3.13
Pinned `.python-version` to `3.13`
❯ uv init
Initialized project `test-code`
❯ ls
README.md main.py pyproject.toml另外一个方式是在init之后添加一个项目名，会自动创建项目文件夹
uv init 项目名如果需要指定特定python版本，建议使用第一种方式来创建项目；
否则还需要手动修改pyproject.toml配置文件里面需要的python版本。
3、添加依赖
uv add 依赖项比如添加requests库：
uv add requests还可以指定具体版本：
uv add requests==版本号执行了这个命令后，会在当前目录下创建.venv虚拟环境目录（在vscode里面可以选择这个目录作为虚拟环境，否则代码解析会有问题）；
并添加我们要的依赖项，同时会新增一个uv.lock文件，用于存放依赖项版本相关的信息。
pyproject.toml文件中的dependencies字段也会包含需要的依赖项：
❯ uv add requests
Using CPython 3.13.1 interpreter at: /opt/homebrew/opt/python@3.13/bin/python3.13
Creating virtual environment at: .venv
Resolved 6 packages in 13.85s
Prepared 5 packages in 5.55s
Installed 5 packages in 13ms
+ certifi==2025.1.31
+ charset-normalizer==3.4.1
+ idna==3.10
+ requests==2.32.3
+ urllib3==2.4.0而且，从这个输出中也能看到，它自动使用了.python-version指定的3.13版本的python；
和当前全局配置下的python3指向什么版本没有关系（全局python3指向的是3.10版本）；
4、运行程序
依赖添加好后，就可以使用uv来运行python程序了
uv run 程序文件名 [命令行参数]uv会自动按照我们的配置来运行程序，无序我们手动维护依赖项，也不需要手动去source各式各样的虚拟环境！
5、其他机器中配置环境
在其他机器拉取代码后，也需要配置虚拟环境、下载项目依赖；
如果使用 uv 进行管理只需要一步：
uv sync即可同步环境，随后使用：
uv run 程序文件名 [命令行参数]即可运行！
六、uvx命令
随着uv下载的还有一个uvx命令，和 pipx 类似；
使用 uvx 命令可以执行或安装一些使用 Python 编写的命令行工具；
参考：
1、临时使用命令
例如，在一个临时环境中执行一个工具：
➜ blog git:(save) ✗ uvx pycowsay 'hello world!'
Installed 1 package in 6ms
/Users/zk/.cache/uv/archive-v0/C-520Z4yR2_MYfgN_xvWl/lib/python3.12/site-packages/pycowsay/main.py:23: SyntaxWarning: invalid escape sequence '\ '
"""
------------
< hello world! >
------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||可以看到，工具会被临时下载到 ~/.cache/uv 中！
2、全局安装工具
也可以全局安装一个工具：
$ uv tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
+ ruff==0.5.0
Installed 1 executable: ruff
$ ruff --version
ruff 0.5.0参考：
uvx命令本质上是uv tool run命令的别名：
uvx python main.py
# 等价于
uv run main.py
# 等价于
uv tool run main.py实际例子，如下这两个命令是等价的：
❯ uvx --directory ~/data/code/python/test_code python main.py
Hello from test-code!
❯ uv tool run --directory ~/data/code/python/test_code python main.py
Hello from test-code!七、配置
1、依赖镜像源配置
参考：
（1）项目级
uv下载第三方库本质上也是通过pypi源下载的，所以在国内网络环境中默认链接速度会很慢，可以在项目目录的pyproject.toml中添加如下内容来使用清华源：
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true（2）命令行级
运行uv add命令的时候也可以指定镜像源
uv add --default-index https://pypi.tuna.tsinghua.edu.cn/simple requests（3）全局
uv也提供了全局的配置项，可以通过环境变量UV_DEFAULT_INDEX配置镜像源
export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple注意：全局的配置项优先级低于pyproject.toml中配置的镜像源；
附录
官方仓库:
官方文档:
参考文章: