python包和项目管理器uv在ubuntu下的安装与使用

一、介绍

uv 是一款用 Rust 编写的超快速 Python 包和项目管理器，可自动下载、管理多版本 Python 解释器，同时提供虚拟环境、极速包安装、项目依赖管理、且兼容传统 pip 工作流。

二、安装步骤

2.1 官网安装步骤

如果你的网络环境允许，可以按官网的指导进行安装：

uv官网安装。

2.2 国内安装步骤

国内环境推荐使用以下方式安装，两种方式二选一。

2.2.1 命令行安装：
打开gitcode同步的官方uv仓库，找到右边的发行版，点开最新版本，按里面的安装方法进行安装，如下：

bash 复制代码

curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.12.5/uv-installer.sh | sh

检验安装：

bash 复制代码

uv --version

2.2.2 自己下载可执行文件安装
打开gitcode同步的官方uv仓库，找到最新的版本，下载linux版本：

下载之后，得到的是一个uv-x86_64-unknown-linux-gnu.tar.gz的压缩包。
解压后，将里面的uv和uvx文件拷贝到$HOME/.local/bin目录下：

bash 复制代码

tar -vxzf uv-x86_64-unknown-linux-gnu.tar.gz
cp uv-x86_64-unknown-linux/* $HOME/.local/bin

添加环境变量：

bash 复制代码

# 在home目录下的.bashrc文件中添加：
export PATH=$PATH:$HOME/.local/bin

验证安装：

bash 复制代码

# 重新打开终端执行
uv --version

2.3 更新uv

bash 复制代码

uv self update

2.4 长时间使用后清理全局缓存

uv 会缓存所有下载的依赖包和 Python 版本，长时间使用后可能占用大量磁盘空间，执行命令一键清理：

bash 复制代码

uv cache clean

三、项目管理

3.1 uv项目管理和传统pip管理对比

先记住：uv 有两套体系，两套体系最好不要混用。

因为：uv sync 会读取 uv.lock来管理环境里全部包；如果中途用 uv pip 装包，uv的lock 文件和实际环境不一致，执行 uv sync 时会覆盖、删掉 pip 安装的包，引发环境不一致。

uv现代体系：UV 原生项目模式（现代、改配置）

现代 uv 项目模式（项目有 pyproject.toml，uv init 创建）
对应命令：uv add / uv remove / uv sync
特点：修改 pyproject.toml + 更新 uv.lock，用于正规项目管理、可复现环境。

uv传统体系：UV PIP 兼容模式（传统、不改配置）

对应命令：uv pip install / uv pip uninstall

示例对比:

对比项目	uv pip install	uv add
修改 pyproject.toml	不改动	添加依赖声明
更新 uv.lock	不更新	更新
依赖追踪	只装到环境，不记录项目声明	项目永久记录依赖，可复现
适用项目	老项目、requirements.txt	uv 管理的项目

3.2 uv项目管理流程

3.2.1、uv传统体系：pip操作 requirements.txt（uv pip）

bash 复制代码

# 创建虚拟环境
uv venv .venv		# 速度远超 python -m venv

# 安装requests包
uv pip install requests

# 卸载requests包
uv pip uninstall requests

# 生成requirements.txt
uv pip freeze > requirements.txt

# 安装requirements.txt
uv pip install -r requirements.txt

# 查看安装包
uv pip list

3.2.2、uv现代体系：项目操作（uv add）

bash 复制代码

#在当前目录初始化一个全新的 uv 管理的 Python 项目，自动生成 pyproject.toml、README等基础文件
uv init  

 # 创建虚拟环境
uv venv .venv

# 添加requests包
uv add requests
uv add ruff --dev     # 开发依赖（仅本地测试、格式化用）
uv add gradio>=6.28.0 # 指定版本

# 卸载requests包（自动从pyproject.toml删除，同时卸载虚拟环境里的包） 
uv remove requests    # 卸载包（自动从pyproject.toml删除，同时卸载虚拟环境里的包） 

# 安装所有：主依赖 + 开发依赖
uv sync

# 只装主依赖（生产/部署必用）
uv sync --no-dev
uv sync --upgrade     # 升级所有依赖并刷新锁文件

# 查看依赖树‌
uv tree

3.3 创建项目

3.3.1、初始化项目‌
bash 复制代码
```
uv init myproject
```
需要指定python版本时
bash 复制代码
```
uv init my-project --python 3.11
```
使用 conda 里的 Python‌时
bash 复制代码
```
uv init my-project --python /path/to/your/python
```
如果不想让uv自动创建src目录，需要加入--no-package参数
bash 复制代码
```
# 加上--no-package, 不会自动创建src目录
uv init my-project --no-package
```

此命令自动生成 pyproject.toml、.python-version 和 .gitignore等文件；

3.3.2、创建/同步环境‌（仅适用于已拿到一个uv项目时使用）
bash 复制代码
```
uv sync
```
此命令会根据已有的uv项目配置，自动安装合适版本的 Python，并自动创建虚拟环境，在 .venv 里装好依赖，并生成 uv.lock 锁定文件。
3.3.3、‌运行命令‌

uv支持自动匹配当前项目的虚拟环境，不用手动激活
bash 复制代码
```
uv run python main.py 
# 或 
uv run pytest
```
想进交互式环境执行
bash 复制代码
```
uv run python
```
运行模块
bash 复制代码
```
uv run python -m http.server
```

3.3.4、‌打包发布‌

bash 复制代码

# 生成发布包
uv build

# 发布到 PyPI
uv publish

3.4 依赖管理与虚拟环境

3.4.1、添加依赖‌

自动更新 pyproject.toml 并安装
bash 复制代码
```
uv add requests
```
指定版本
bash 复制代码
```
uv add numpy==1.26.4
```
添加开发依赖‌（只用于开发、不打包）
bash 复制代码
```
uv add pytest --dev
```
uv add命令执行后，会自动创建venv虚拟环境，并将要添加的包安装到虚拟环境中。
3.4.2、删除依赖‌
bash 复制代码
```
uv remove requests
```
3.4.3、查看依赖树‌
bash 复制代码
```
uv tree
```
3.4.4、同步依赖‌

拿到一个uv项目，或手动编辑 pyproject.toml 后，需要执行
bash 复制代码
```
# 按配置安装或更新
uv sync
```
3.4.5、生成/更新锁文件‌
bash 复制代码
```
uv lock	# 一般 uv sync 会自动做
```
3.4.6、pip 兼容命令‌

习惯 pip 的话也能用，但不推荐

bash 复制代码

uv pip install -r requirements.txt

uv pip list

uv pip freeze

四、多Python版本管理

uv 能自己下载和管理多个 Python 版本，不用装 pyenv。

4.1 安装python版本‌

uv 会自动下载对应平台的预编译二进制包，无需本地编译

bash 复制代码

uv python install 3.10 3.11 3.12

也可以指定精确的补丁版本进行安装：

bash 复制代码

uv python install 3.12.4

4.2 查看所有 Python 版本

查看已装的python版本‌

bash 复制代码

uv python list

4.3 固定项目版本‌

bash 复制代码

uv python pin 3.12.9

此命令会生成 .python-version 文件，团队成员拉下来后uv sync自动用同一版本。

4.4 查看项目实际使用的Python路径

bash 复制代码

uv python find

此命令会获取 uv 当前解析到的 Python 解释器绝对路径，用于排查版本冲突问题。

4.5 卸载 Python 版本

清理不需要的 Python 版本，释放磁盘空间：

bash 复制代码

uv python uninstall 3.10

五、虚拟环境管理

uv 会自动管理虚拟环境，也支持手动创建、激活、删除等全操作。

5.1 创建虚拟环境

5.1.1、自动创建默认虚拟环境：

你无需手动执行创建命令，当你第一次执行 uv add 或 uv sync 时，uv 会自动在项目目录下生成 .venv 虚拟环境文件夹。
5.1.2、手动指定 Python 版本创建虚拟环境：
bash 复制代码
```
uv venv --python 3.11
```
5.1.3、自定义虚拟环境名称和路径：
bash 复制代码
```
uv venv my-custom-venv
```

5.2 激活与退出虚拟环境

uv 推荐使用 uv run 直接运行命令，无需手动激活环境，避免环境切换混乱。如果你需要手动进入虚拟环境：

bash 复制代码

source .venv/bin/activate

手动激活后，终端提示符前会出现 (.venv) 标识，执行 deactivate 命令即可退出虚拟环境，回到系统默认环境。

5.3 删除虚拟环境

直接删除虚拟环境文件夹即可完成清理：

bash 复制代码

rm -rf .venv

六、配置下载源

可以为 uv 配置下载源，包括 PyPI 包源和 Python 解释器源。

6.1 配置 PyPI 包源

6.1.1、命令行临时指定（单次生效）
在执行安装命令时，通过
--index-url 参数直接指定源，仅对当前命令生效。
示例：
bash 复制代码
```
uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy
```
6.1.2、环境变量配置（当前会话生效）
设置环境变量 UV_PIP_INDEX_URL来指定源，仅在当前终端会话中生效。
bash 复制代码
```
export UV_PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple  
```
6.1.3、配置文件永久配置（全局生效）
在用户主目录下创建或修改 uv 的配置文件，对所有项目生效。
创建或添加~/.config/uv/uv.toml文件，配置内容示例（以清华源为例）：
txt 复制代码
```
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
```
6.1.4、项目级配置（仅对当前项目生效）
在项目的根目录（与pyproject.toml 同级）创建或修改uv.toml文件，或直接在pyproject.toml 中配置。
- uv.toml 配置示例：
txt 复制代码
```
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
```
- pyproject.toml 配置示例（需加tool.uv前缀）：
txt 复制代码
```
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
```

6.2 配置 Python 解释器源

6.2.1、环境变量配置（当前会话生效）

设置环境变量UV_PYTHON_INSTALL_MIRROR来指定 Python 解释器的下载源。

示例：
bash 复制代码
```
export UV_PYTHON_INSTALL_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/python/
```
6.2.2、配置文件永久配置（全局生效）

在 uv 的配置文件~/.config/uv/uv.toml中添加python-install-mirror字段。

配置内容示例：
txt 复制代码
```
python-install-mirror = "https://mirrors.tuna.tsinghua.edu.cn/python/"
```

6.3、常用国内镜像源地址参考

6.3.1、PyPI 源：
- 清华大学：https://pypi.tuna.tsinghua.edu.cn/simple
- 阿里云：https://mirrors.aliyun.com/pypi/simple
- 中国科学技术大学：https://pypi.mirrors.ustc.edu.cn/simple
6.3.2、Python 解释器源：
- 清华大学：https://mirrors.tuna.tsinghua.edu.cn/python/
- 阿里云：https://mirrors.aliyun.com/python/

6.4、验证配置是否生效

6.4.1、对于 PyPI 源，执行
py 复制代码
```
uv pip install -v 包名
```
观察输出日志中是否显示配置的源地址。
6.4.2、对于 Python 解释器源，执行
py 复制代码
```
uv python download 版本号
```
观察下载速度是否明显提升。