【保姆级喂饭教程】uv教程一文讲透：安装，创建，配置，工具，命令

荔枝吻

已于 2025-08-01 17:30:03 修改

阅读量847

点赞数 41

CC 4.0 BY-SA版权

分类专栏： Python # 【保姆级喂饭教程】文章标签： uv python

于 2025-08-01 16:29:46 首次发布

本文链接：https://blog.csdn.net/AlienProgrammer/article/details/149743804

【保姆级喂饭教程】同时被 2 个专栏收录

12 篇文章

订阅专栏

Python

8 篇文章

订阅专栏

请添加图片描述

前言

在使用PyCharm 2022.3.2创建新项目的时候，可以选择四种虚拟环境：virtualenv，pipenv，poetry，conda，由于对这些并不是十分的了解，深入梳理后发现最新最流行的是uv
【保姆级喂饭教程】Python依赖管理工具大全：Virtualenv、venv、Pipenv、Poetry、pdm、Rye、UV、Conda、Pixi等

在这里插入图片描述

一、安装uv

PyCharm 2022.3.2中并未支持 New Project 创建uv项目，毕竟uv库2024年才发布，所以需要自己安装一下。

1. 安装方式

uv：GitHub | docs
安装方式有三种：

通过powershell的irm命令下载二进制文件并安装
当然也可以在GitHub上直接下载，再手动安装
通过pip命令从PyPi直接安装库到全局环境

我比较推荐用第一种，单独安装uv：https://docs.astral.sh/uv/getting-started/installation/

对比项	PowerShell安装	pip安装
环境依赖	无需Python环境	需要现有Python环境
路径配置	自动添加系统PATH	需手动添加脚本路径
更新管理	uv self update一键更新	需通过pip更新
执行速度	预编译二进制，速度更快	可能需编译组件
系统影响	独立安装，干净隔离	可能污染现有Python环境

pip安装方式建议

需要特定版本时（如 pip install uv==0.1.36）
在隔离的容器环境中
没有PowerShell执行权限时

修改安装目录：https://docs.astral.sh/uv/reference/installer/
在这里插入图片描述

2. cmd自动安装

综上，用管理员打开cmd，按照官方教程输入安装命令后回车，安装目录更换为自己的目录，提前创建一个空文件夹

powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "D:\Program\Work\uv";irm https://astral.sh/uv/install.ps1 | iex}

在这里插入图片描述

命令解释：

部分	说明
`powershell`	启动PowerShell解释器
`-ExecutionPolicy ByPass`	临时绕过安全策略允许执行远程脚本（默认禁止）
`-c`	指定要执行的命令（`-Command`缩写）
`"irm https://astral.sh/uv/install.ps1"`	`irm` = `Invoke-RestMethod` 下载官方安装脚本
`iex`	管道符连接`iex` = `Invoke-Expression` 立即执行下载的脚本

报错了，应该是花括号的问题，不知道官方是在什么系统里执行的
在这里插入图片描述
换成双引号，又报错了，双引号中的双引号要换成单引号

网络错误

ps：单独下载install.ps1文件（.ps1文件是PowerShell脚本文件的标准扩展名），里面可以看到从GitHub下载二进制文件，所以需要挂梯子
脚本下载链接：uv-installer-0.8.3.ps1
AI分析脚本：【AI分析】uv库自动安装脚本uv-installer-0.8.3.ps1分析

打开梯子，最终正确命令如下：

powershell -ExecutionPolicy ByPass -c "$env:UV_INSTALL_DIR = 'D:\Program\Work\uv';irm https://astral.sh/uv/install.ps1 | iex"

安装成功
在这里插入图片描述

验证，安装完成后，在新的cmd窗口执行：

uv -V

在这里插入图片描述

3. powershell自动安装

上面关于命令的解释可以看到，cmd其实是调用powershell执行脚本，当然也可以直接在powershell中执行

$env:UV_INSTALL_DIR = 'D:\Program\Work\uvtest';irm https://astral.sh/uv/install.ps1 | iex

正常执行，由于我已经安装了，出现下载就直接关掉了
在这里插入图片描述

4. 手动安装

有时候梯子不稳定或者网速太慢怎么办呢，回顾上面的安装日志，简单分析安装脚本，其实就是下载三个exe，然后设置个环境变量就可以，脚本内部会根据系统自动选择下载对应版本

打开GitHub的release页面，选择最新版对应自己系统的文件：https://github.com/astral-sh/uv/releases
在这里插入图片描述
下载后解压到安装目录

搜索打开编辑系统环境变量

把uv目录添加到环境变量-用户变量-path中，多系统用户也可以添加到系统变量-path中

提供一个Windows64位的安装包：uv-x86-64-pc-windows-msvc-0.8.3.zip

5. 修改目录

在写到二、创建uv项目 - 3.3 换源-GitHub加速时需要修改uv的默认python安装目录，由于还有很多工作目录，索性全都改到D盘，根据文章结构，插入写到这里

这一步需要根据自己的需求自行调整，全部修改会创建许多的环境变量，可以根据自己需要减少

根据在环境变量页面搜索dir，https://docs.astral.sh/uv/reference/environment/，可以找到所有的目录和文件环境变量：

UV_CACHE_DIR：等同于命令行参数 --cache-dir。如果设置，uv 将使用此目录进行缓存，而不是默认的缓存目录。
UV_CONFIG_FILE：等同于命令行参数 --config-file。期望一个本地 uv.toml 文件的路径，用作配置文件。
UV_INSTALL_DIR：使用独立安装程序和 self update 功能安装 uv 的目录。默认为 ~/.local/bin。
UV_PYTHON_BIN_DIR：指定放置指向已安装、受管理的 Python 可执行文件的链接的目录。
UV_PYTHON_CACHE_DIR：指定在安装前缓存受管理 Python 安装档案的目录。
UV_PYTHON_INSTALL_DIR：指定用于存储受管理的 Python 安装的目录。
UV_TOOL_BIN_DIR：指定用于安装工具可执行文件的"bin"目录。
UV_TOOL_DIR：指定 uv 存储管理工具的目录。

根据在命令页面搜索环境变量，主要使用三个工作目录

C:\Users\用户名\AppData\Local\uv：主要放cache、python cache
C:\Users\用户名\AppData\Roaming\uv：主要放python install、tool、uv.toml
C:\Users\用户名.local\bin：install、python bin、tool bin

也可以用命令查看

uv cache dir # 查看缓存路径  UV_CACHE_DIR、UV_PYTHON_CACHE_DIR
uv python dir # 查看python安装路径  UV_PYTHON_INSTALL_DIR
uv python dir --bin # 查看python bin安装路径  UV_PYTHON_BIN_DIR
uv tool dir # 查看工具安装路径  UV_TOOL_DIR
uv tool dir --bin # 查看工具安装路径  UV_TOOL_BIN_DIR

在这里插入图片描述

为什么修改python安装目录也要修改cache缓存目录呢？

uv 使用缓存来避免重新下载（和重新构建）在先前运行中已经访问过的依赖项。
windows 下默认为硬链接 hardlink 模式，意味着文件系统中只有一个文件，这样可以减少磁盘占用，这对多个虚拟环境开发非常有用。
由于硬链接不支持跨卷访问（不同盘符），因此缓存目录要和 uv 正在运行的 Python 环境位于相同的文件系统（盘符）上。否则，uv 将无法将缓存中的文件链接到环境中，而将需要回退到缓慢的copy操作。

下面进行修改，先清空下缓存吧

uv cache clean # 从缓存目录中删除所有缓存条目，将其彻底清除。
uv cache purge # 删除所有未使用的缓存条目

在这里插入图片描述

依次执行下面命令

setx UV_HOME "D:\Program\Work\uv" # 替换为安装时选择的目录
setx UV_CACHE_DIR "%UV_HOME%\cache"
setx UV_CONFIG_FILE "%UV_HOME%\uv.toml"
setx UV_INSTALL_DIR "%UV_HOME%\bin"
setx UV_PYTHON_BIN_DIR "%UV_HOME%\bin"
setx UV_PYTHON_CACHE_DIR "%UV_HOME%\cache"
setx UV_PYTHON_INSTALL_DIR "%UV_HOME%\python"
setx UV_TOOL_BIN_DIR "%UV_HOME%\bin"
setx UV_TOOL_DIR "%UV_HOME%\tools"

在这里插入图片描述

在环境变量里面确认
在这里插入图片描述
还需要把python bin目录加到path变量中，但是setx命令只能处理1024字符，很容易截断变量值并导致系统变量损坏。

setx PATH "%PATH%;%UV_PYTHON_BIN_DIR%"

而path中不能使用变量引用， PATH 里不会二次展开。
Windows 的 PATH（无论是系统还是用户）只把 %…% 当成普通字符存进去，不会在启动 cmd 时再解析一次。
所以手动加一条D:\Program\Work\uv\bin
在这里插入图片描述

否则会报一个警告：
warning: D:\Program\Work\uv\bin is not on your PATH. To use installed Python executables, run $env:PATH = "D:\Program\Work\uv\bin;$env:PATH" or uv python update-shell.
根据提示，也可以使用 uv python update shell 命令自动设置

重新打开一个cmd进行确认，目录都修改成功了，但是uv命令不能直接使用了，暂不知是什么问题
在这里插入图片描述

总结

环境变量	默认目录	查看命令	修改目录	解释
UV_CACHE_DIR	AppData\Local\uv\cache	uv cache dir	cache	等同于命令行参数 --cache-dir。如果设置，uv 将使用此目录进行缓存，而不是默认的缓存目录。
UV_CONFIG_FILE	AppData\Roaming\uv\uv.toml		uv.toml	等同于命令行参数 --config-file。期望一个本地 uv.toml 文件的路径，用作配置文件。
UV_INSTALL_DIR	.local\bin		bin	使用独立安装程序和 self update 功能安装 uv 的目录。默认为 ~/.local/bin。
UV_PYTHON_BIN_DIR	.local\bin	uv python dir --bin	bin	指定放置指向已安装、受管理的 Python 可执行文件的链接的目录。
UV_PYTHON_CACHE_DIR	AppData\Local\uv\cache	uv cache dir	cache	指定在安装前缓存受管理 Python 安装档案的目录。
UV_PYTHON_INSTALL_DIR	AppData\Roaming\uv\python	uv python dir	python	指定用于存储受管理的 Python 安装的目录。
UV_TOOL_BIN_DIR	.local\bin	uv tool dir --bin	bin	指定用于安装工具可执行文件的"bin"目录。
UV_TOOL_DIR	AppData\Roaming\uv\tools	uv tool dir	tools	指定 uv 存储管理工具的目录。

6. 卸载

卸载同理，把uv文件夹删除，把环境变量删除

二、创建uv项目

需要先通过uv命令初始化项目，之后用pycharm打开项目进行后续的开发

1. uv项目结构

推荐先在文件资源管理器中创建项目文件夹，防止在命令中输错后额外生成错误文件
在这里插入图片描述
直接在当前目录路径窗口输入cmd，打开cmd后自动进入当前路径

使用uv初始化项目

uv init

创建了一些基础文件和git，还没有创建虚拟环境，这个后面说
在这里插入图片描述
默认项目结构：

project/
├── .git/
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

.gitignore

# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

# Virtual environments
.venv

.python-version

3.10

main.py

def main():
    print("Hello from uv-test!")


if __name__ == "__main__":
    main()

pyproject.toml

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

README.md 为空

2. 创建项目

其实创建完空文件夹后就可以用pycharm打开，然后在terminal命令行用uv init进行初始化，只不过pycharm打开会创建一个main.py，上面为了看看uv创建的文件内容，选择了在cmd命令行中初始化。下面重新来一遍。

先在文件资源管理器中创建项目文件夹，防止在命令中输错后额外生成错误文件
在这里插入图片描述
重新打开pycharm，才能更新环境变量，点击 File - Open 准备打开刚刚的项目

选择刚刚创建的文件夹，点击ok

点击下方导航栏的Termai，输入 uv init 进行初始化

uv init

在这里插入图片描述
如果文件没变化，就手动刷新一下

接下来就可以按照需求进行开发了

3. python版本

在开始开发前，还是要单独说下python版本的问题，毕竟这是一个python项目的基础。
在使用 uv init 初始化后，生成了一个.python-version文件，里面写了当前项目的版本，uv默认选择电脑上最新的python版本

首先查看一下uv支持的python版本列表

uv python list

可以看到一共有三大类，有官方的cpython，也有三方发布的pypy和graalpy，后面有<download available的表示可以下载，蓝色路径表示已经安装的版本，我这里只有3.10，所以之前创建的项目默认就是3.10
【AI总结】全网最全 2025 版！Python 九种解释器「全家福」超深度横评
 【AI总结】Python解释器全景解析：从CPython到GraalPython的深度对比
在这里插入图片描述
新项目，我们就换个新版本，3.14还是预发版本，那就安装个默认最新版和3.13.5

uv python install # 安装最新版本
uv python install 3.13 # 安装指定版本

可以看到最新版本其实是python3.10.18
又是从GitHub上下载，最简单的当然是打开梯子
在这里插入图片描述

下面对各种方法做一个总结

3.1 科学上网

换了几个节点都不行，可能是节点质量不行，但是Google和GitHub都能打开，不管了，先换别的方法

3.2 换源-国内镜像

由于各类仓库和GitHub都在国外，目前的网络都无法直接访问，一些企业或者高效针对比较常用的仓库搭建了开源镜像，python的独立构建仓库python-build-standalone有很多的分发仓库，uv默认从作者astral-sh搭建的GitHub分发仓库下载，所以下载不下来，能搜索到的只有南京大学镜像和阿里云镜像

# 南京大学镜像
https://mirror.nju.edu.cn/github-release/indygreg/python-build-standalone
# 阿里云镜像
https://registry.npmmirror.com/-/binary/python-build-standalone

换源有四种方法，优先级为：命令行 > 项目文件配置 > 环境变量 > 全局文件配置
详细版：命令行 --mirror > 命令行 $env > 项目配置文件 uv.toml > 项目配置文件 pyproject.toml > 系统环境变量 > 全局配置文件 uv.toml
配置文档：https://docs.astral.sh/uv/concepts/configuration-files/
在这里插入图片描述

下面简单介绍一下

3.2.1 全局环境变量

环境变量官方文档：https://docs.astral.sh/uv/reference/environment/

系统环境变量永久设置
系统-环境变量-新建
UV_PYTHON_INSTALL_MIRROR
https://registry.npmmirror.com/-/binary/python-build-standalone
命令行临时设置环境变量

$env:UV_PYTHON_INSTALL_MIRROR="https://registry.npmmirror.com/-/binary/python-build-standalone"

在这里插入图片描述

3.2.2 全局配置文件

uv的配置文件默认藏在这里：Windows：C:\Users\你的用户名\AppData\Roaming\uv\uv.toml，可能是因为还没设置过，也没有这个文件，创建一个txt，改名为uv.poml，填入镜像地址

[tool.uv]
python-install-mirror = "https://mirror.nju.edu.cn/github-release/indygreg/python-build-standalone"

在这里插入图片描述

后续对配置目录进行了调整，详见一、安装uv - 5. 修改目录，所以需要移动到uv的安装目录中

这个测试一下，位置没问题，写法不对
在这里插入图片描述
查下官方文档，uv.toml里面不用写[tool.uv]
https://docs.astral.sh/uv/reference/settings/#python-install-mirror

正确命令

python-install-mirror = "https://mirror.nju.edu.cn/github-release/indygreg/python-build-standalone"

南京大学镜像本身镜像就不全，对应地址也打不开，这也不知道是没有还是镜像源挂了
在这里插入图片描述

python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone"

仍然没有
在这里插入图片描述
访问镜像地址发现阿里云镜像上的目录只到20250612，而uv非要从20250723里面下载

3.2.3 项目配置文件

由于两个镜像都不能用，就不做截图了

在 pyproject.toml 中添加：

[tool.uv]
python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone"

在这里插入图片描述

或在 uv.toml 中添加，初始化后项目内是没有uv.toml的，自己创建一个：

python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone"

在这里插入图片描述

uv.toml 文件优先于 pyproject.toml 文件，因此如果目录中同时存在 uv.toml 和 pyproject.toml 文件，配置将从 uv.toml 中读取， [tool.uv] 部分在随附的 pyproject.toml 中将被忽略。

3.2.4 单次命令

单次命令配置只在这一条命令生效

uv python install --mirror https://registry.npmmirror.com/-/binary/python-build-standalone

在这里插入图片描述

3.3 换源-GitHub加速

本质与更换镜像源一样，也是换源的那四种方法，由于下载仓库是全局的，所以推荐采用全局配置文件的方式，其他不再展示
如果是团队协作，那就推荐同时写到项目内的配置文件uv.toml中

python-install-mirror = "https://gitproxy.click/https://github.com/indygreg/python-build-standalone/releases/download"

在这里插入图片描述
这个可行

默认安装到 C:\Users\用户名\AppData\Roaming\uv\python 下

c盘已经很满了，修改安装位置再安装一次，同时也要改缓存目录，索性把所用工作目录都改到d盘，详见一、安装uv - 5. 修改目录
更改后再安装一个python 3.13
在这里插入图片描述

位置正确
在这里插入图片描述

卸载3.10.18
重新打开以后已经找不到之前默认安装的3.10.18版本了，因为python目录已经改变了，直接把uv的相关文件夹删除就行：C:\Users\Alien\AppData\Roaming\uv

正常卸载用

uv python uninstall 3.10.18

3.4 换源-手动下载

如果换源也不行的话，就只能尝试手动下载了，然后配置下载路径到本地，本质还是换源，哈哈哈。

根据前面的错误可以看到，下载的文件名称是cpython-3.10.18%2B20250723-x86_64-pc-windows-msvc-install_only_stripped.tar.gz，其中x86_64和pc-windows根据自己的系统调整
在这里插入图片描述
我们以3.10.18示例

3.4.1 astral-sh

https://github.com/astral-sh/python-build-standalone/releases
展开附件，有足足649个
在这里插入图片描述

先找3.10.18，再找x86_64和pc-windows，发现有两个，链接太长显示不全，鼠标放上去，浏览器下方会显示完整的链接，选择最后面有stripped的
在这里插入图片描述
也可以直接在页面搜索cpython-3.10.18+20250723-x86_64-pc-windows-msvc-install_only_stripped.tar.gz

放到一个文件夹里

用单次命令测试一下

uv python install 3.12 --mirror file:///D:\Program\Work\uv\python-mirror

uv会自动补个日期路径
在这里插入图片描述
我们在文件夹再创建一层

命令不变，安装只用1秒，用GitHub加速的话要10秒左右

3.4.2 阿里

还是之前找到的镜像源：https://registry.npmmirror.com/-/binary/python-build-standalone
找到最后一个最新的链接
在这里插入图片描述
搜索找到想要的链接，直接访问就可以下载，后面的同上

3.5 搭建本地镜像

有开发者通过之前对uv github上源码的分析，发现有一键创建本地镜像的脚本，本质就是换源-手动下载改为自动，但是自动下载那不又回到了网络问题

脚本位于uv\scripts\create-python-mirror.py，github脚本地址
可以一键下载全部镜像到当前目录的mirror文件下
脚本的下载需要配置元数据进行下载：uv\crates\uv-python\download-metadata.json
路径必须一致，否则需要修改脚本VERSIONS_FILE定义

VERSIONS_FILE = REPO_ROOT / "crates" / "uv-python" / "download-metadata.json"

修改为

VERSIONS_FILE = SELF_DIR / "download-metadata.json"

将download-metadata.json放置当前目录下， github下载链接
使用uv run create-python-mirror.py命令即可自动下载镜像库
元数据内容应该回随着版本更新更新，所以更新uv版本的时候可以更新镜像库
这边下载测试了一下，截至20250409的版本目前总镜像大小大约为11g左右
并且生成本地镜像库本地地址与使用案例

UV_PYTHON_INSTALL_MIRROR='file://D:\uv\scripts\mirror' 
uv python install 3.13

将mirror文件添加到web服务器上即可实现本地镜像库的搭建

3.6 自建代理

本质和使用节点科学上网一样，比较麻烦，就不测试了
国内加速安装 uv Python 的终极方案：自建智能代理站

4. 切换python版本

为了和安装python区分，另起一节。

目前.python-version里面还是3.10
在这里插入图片描述
uv python list 看看有哪些python版本

修改版本就是修改上面的文件

uv python pin 3.13

在这里插入图片描述
小提示：通过uv python pin 3.13命令修改python版本，并不会影响系统级别的python版本，该设置主要是固定当前项目 Python 版本

5. 项目开发

接下来就正式进入开发了

5.1 安装依赖

在uv种使用add安装库，第一次安装库会自动生成.venv虚拟环境，也可以用uv venv单独创建
用pandas测试一下速度，大概花费8.4s

uv add pandas

在这里插入图片描述
同时创建一个uv.lock文件，uv.lock 是 uv 工具为 Python 项目生成的一个跨平台依赖锁定文件，它的核心作用是：
记录项目中所有依赖及其子依赖的精确版本，确保在不同机器、不同时间安装的结果完全一致。

在这里插入图片描述
区别于pip install，uv add会把依赖添加到项目pyproject.toml文件的依赖列表里，当你uv sync的时候将会编译生成到uv.lock里。

5.2 卸载依赖

卸载的十分快，其实只是删除了链接

uv remove pandas

在这里插入图片描述

5.3 pypi换源

python的一大优势是有各种各样便捷的三方依赖库，很不幸，pypi库也在国外，下载起来会慢一些，不过这个的镜像就多了

推荐在项目和全局的uv.toml同时配置，方便个人单体项目和团队协作项目

python-install-mirror = "https://gitproxy.click/https://github.com/indygreg/python-build-standalone/releases/download"

[[index]]
name = "tsinghua" # 清华源
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

[[index]]
name = "aliyun" # 阿里云源
url = "https://mirrors.aliyun.com/pypi/simple"

default = true 表示这是默认的主镜像源，优先级最高。
后面的 [[index]] 条目会作为备用镜像源，当默认源找不到包时，会依次尝试这些源。
与 pip 不同，uv 不会读取 pip.conf，所以必须通过 uv.toml 或环境变量来配置镜像源。
如果你同时使用环境变量（如 UV_DEFAULT_INDEX），它会覆盖配置文件中的设置。

但是官方说有default = true的镜像源是最低优先级，我表示怀疑，之后有机会验证一下
https://docs.astral.sh/uv/reference/settings/#index
在这里插入图片描述

给之前的缓存都删除
在这里插入图片描述
1s！！！这就是差距，哈哈哈，真快

5.4 配置pycharm解释器

虽然uv是基于python 3.13.5创建的虚拟环境，但是pycharm无法感知到，默认的还是打开项目时自动选择的解释器，需要给它换成uv设置的

右下角点击python解释器，选择add新增，选择本地
在这里插入图片描述
选择虚拟环境，选择已存在，刚刚uv已经创建了

默认叫了个 3.10（uv-test），看着难受，改一下，打开解释器设置

在这里插入图片描述

这里扫不到包应该是3.11以后没有setuptools库了，pycharm就识别不出来，不过我们用uv命令，不影响使用。

5.5 项目开发

创建项目文件，继续安装或删除依赖，编写代码
在这里插入图片描述
设置个文件夹类型

设置src为蓝色的Sources，其他tests、docs以此类推

5.6 项目运行

使用uv run运行文件，该命令会自动激活虚拟环境，如果没有也会自动创建

uv run src\main.py

在这里插入图片描述
由于新增了python解释器，感觉和在pycharm运行没有什么区别，pycharm更方便一些

5.7 同步环境

一个人开发一般不需要，团队协作时如果别人安装了依赖我们拉取git后也得安装，前面说过uv通过uv.lock管理和锁定依赖版本，拉取后会得到别人的uv.lock文件，只需按照lock安装一下就好，类似pip的requirement.txt

uv sync

在这里插入图片描述

5.8 依赖管理

这一步非必要，顺便提一下

5.8.1 查看依赖

uv tree                          # 查看依赖树
uv pip list                      # 查看已安装包
uv pip show pandas               # 查看包详情

uv tree展示的是以uv add安装的库为目录，展开依赖层级引用关系，重复的也显示
在这里插入图片描述
uv pip list展示的是依赖引用安装完后的实际列表，没有重复

uv pip show pandas则查看某个库的详细情况

5.8.2 升级依赖

简单提一下升级依赖，一般来说用不着，除非必须用新版本提供的功能。
升级依赖可能会造成错误，引起不必要的麻烦

uv lock --upgrade-package numpy  # 仅升级 numpy 并更新 lock
uv lock --upgrade                # 全量升级到最新兼容版本
uv sync                          # 把升级结果安装到 venv

5.8.3 uv pip

uv仍然兼容使用pip管理包，在pip命令前面增加uv即可

uv pip compile # 将requirements.in文件编译为requirements.txt或pylock.toml文件
uv pip sync # 同步一个带有requirements.txt或pylock.toml文件的环境
uv pip install # 将包安装到环境中
uv pip uninstall # 从环境中卸载软件包
uv pip freeze > requirements.txt # 以需求格式列出环境中已安装的包，例如requirements.txt
uv pip list # 以表格形式列出环境中已安装的包
uv pip show # 显示一个或多个已安装软件包的信息
uv pip tree # 显示环境的依赖关系树
uv pip check # 验证已安装的包是否具有兼容的依赖项

5.9 打包发布

打包发布用的比较少，简单说明一下

uv build # 生成 sdist & wheel
uv publish # 上传到 PyPI（需 token）

什么时候需要「打包」（build）？

场景	典型命令	目的
✅ 公司内部其他团队或同事想 `pip install 你的项目`	`uv build` → 把生成的 `.whl` 丢到内部制品库 / 共享目录	让别人能装
✅ 部署到服务器 / Docker 镜像	`docker build` 里 `pip install dist/*.whl`	避免每次都从源码装
✅ 给测试/QA 一个可复现的安装包	同上	保证版本一致
✅ 最终要上传到 PyPI 或私有仓库	前置步骤	生成标准格式

什么时候需要「发布」（publish）？

目标仓库	是否必须发布	说明
公共 PyPI	可选	只有开源项目才需要，公司代码一般不上传。
公司私有仓库（Nexus、JFrog、Artifactory、GitLab Package Registry…）	可选	方便团队共享，需配置 `uv publish --index <私有源>`。

5.9.1 uv build

官方文档：https://docs.astral.sh/uv/reference/cli/#uv-build

将Python包构建为源码发行版和wheel格式。
uv build 接受一个目录或源码分发的路径，默认为当前工作目录。
默认情况下，如果传入一个目录，uv build会从源目录构建一个源码发行版(“sdist”)，并从源码发行版构建一个二进制发行版(“wheel”)。
uv build --sdist 可用于仅构建源码分发包，uv build --wheel 可用于仅构建二进制分发包，而 uv build --sdist --wheel 可用于从源码同时构建两种分发包。
如果传入一个源码发行版，uv build --wheel 会从源码发行版构建一个wheel包。

uv build [OPTIONS] [SRC]

SRC
用于构建分发的目录，或是需要构建为wheel的源码分发归档文件。
默认为当前工作目录。

5.9.2 uv publish

官方文档：https://docs.astral.sh/uv/reference/cli/#uv-publish

上传分布数据到索引

uv publish [OPTIONS] [FILES]...

FILES
要上传的文件路径。支持glob表达式。
默认为dist目录。仅选择wheel包和源码发行版，同时忽略其他文件。

三、使用uv工具

官方文档-使用工具：https://docs.astral.sh/uv/guides/tools/
官方文档-工具：https://docs.astral.sh/uv/concepts/tools/

1. 临时工具

uv 提供了一个专用接口用于与工具交互。无需安装即可通过 uv tool run 调用工具，此时它们的依赖项会被安装在与当前项目隔离的临时虚拟环境中。
由于在不安装工具的情况下运行它们非常常见，因此提供了一个uvx别名来代替uv tool run——这两个命令完全等效。

当使用uvx运行工具时，虚拟环境会被存储在uv缓存目录中，并被视为可丢弃的。也就是说，如果你运行uv cache clean，该环境将被删除。缓存环境仅用于减少重复调用的开销。如果环境被移除，系统会自动创建一个新的。

uvx ruff
uv tool run ruff # 与上面完全相同

在这里插入图片描述

2. 本地工具

如果一个工具经常被使用，将其安装到持久化环境并添加到PATH中比反复调用uvx更为实用。
或者如果你在项目中运行一个工具，且该工具要求你的项目已安装（例如使用pytest或mypy时），你应该使用uv run而不是uvx。否则，该工具将在与你的项目隔离的虚拟环境中运行。

可以通过uv tool install命令安装工具，这种情况下它们的可执行文件将在PATH环境变量中可用——系统仍会使用隔离的虚拟环境，但该环境在命令完成后不会被删除。

当使用uv tool install安装工具时，会在uv工具目录中创建一个虚拟环境。除非卸载该工具，否则不会移除该环境。如果手动删除该环境，工具将无法运行。

uv tool dir # 查看工具目录
uv tool install ruff@latest # 安装最新版ruff

uv tool uninstall ruff # 卸载ruff

在这里插入图片描述

安装完以后可直接使用

ruff -V
ruff check .

在这里插入图片描述
如果需要用到虚拟环境中的库，在工具命令前面加上uv run，推荐统一用这个

uv run ruff -V
uv run ruff check .

在这里插入图片描述

3. 项目工具

也可以选择把工具安装到项目中，这样别人可以通过uv.lock文件进行同步工具版本，也可以对工具进行详细配置

uv add --dev ruff

在这里插入图片描述

4. ruff

ruff github：https://github.com/astral-sh/ruff
ruff docs：https://docs.astral.sh/ruff/
AI总结：【AI总结】一篇吃透 Ruff CLI：从入门到进阶的完整命令手册

单独推荐一下这个超级推荐的工具，uv作者出品，也是用rust编写
Ruff = Black + Flake8 + isort + pyupgrade！没错，四合一，非常高效好用。

4.1 核心命令一览

子命令	作用	高频示例
`ruff check`	代码静态检查（Lint）	`ruff check .`
`ruff format`	代码格式化（Black 替代）	`ruff format .`
`ruff fix`	仅执行自动修复	`ruff fix . --unsafe`
`ruff rule`	查看规则详情	`ruff rule E501`
`ruff list`	列出所有规则	`ruff list --format json`
`ruff clean`	删除本地缓存	`ruff clean`
`ruff version`	查看版本	`ruff version`
`ruff help`	查看帮助	`ruff help check`

4.2 `ruff check` 常用参数

ruff check .                         # 递归检查当前目录
ruff check --fix                     # 自动修复可修复项
ruff check --unsafe                  # 启用可能不安全的修复
ruff check --watch                   # 监听文件变化实时检查
ruff check --select E,W              # 仅跑 E、W 类规则
ruff check --ignore F401,E501        # 忽略指定规则
ruff check --config ruff.toml        # 显式指定配置文件
ruff check --output-format json      # JSON 输出（适合 CI）

4.3 `ruff format` 常用参数

ruff format .                        # 原地格式化
ruff format --check                  # 仅检查是否已格式化
ruff format --diff                   # 打印 diff，不修改文件

4.4 配置优先级（可放任意一个）

pyproject.toml（推荐）
ruff.toml
.ruff.toml

示例最小配置：

[tool.ruff]
line-length = 88
target-version = "py311"
select = ["E", "F", "W", "I"]     # I=isort 规则
ignore = ["E501"]

4.5 典型工作流（本地+CI）

# 1. 本地：一键修复+格式化
ruff check --fix . && ruff format .

# 2. CI：只检查不修改
ruff check . --output-format github
ruff format . --check

4.6 与 uv 的结合

# 临时跑（免安装）
uvx ruff check .

# 长期安装到全局
uv tool install ruff
ruff check .

4.7 规则速查

E：PEP8 风格
F：Pyflakes 逻辑错误
W：pycodestyle 警告
I：isort 排序
C90：McCabe 复杂度
UP：pyupgrade 升级语法

查看全部：

ruff list --format json | jq '.[].code'

5. 常用工具

仅供参考：

包名	提供的可执行命令	典型用途
ruff	ruff	代码检查 + 格式化
black	black	代码格式化
pytest	pytest	单元测试
mypy	mypy	静态类型检查
httpie	http / https / httpie	HTTP 客户端
mkdocs	mkdocs	文档站点生成
django	django-admin	Django 管理命令
ansible	ansible / ansible-playbook	运维自动化
pre-commit	pre-commit	Git 钩子
pip-audit	pip-audit	依赖安全扫描
pycowsay	pycowsay	彩蛋/演示

四、流程总结

前面的内容毕竟丰富，这里重新总结一下，只选取实际操作的内容

1. cmd安装uv

powershell -ExecutionPolicy ByPass -c "$env:UV_INSTALL_DIR = 'D:\Program\Work\uv';irm https://astral.sh/uv/install.ps1 | iex"

2. 配置环境

删除uv工作目录

C:\Users\用户名\AppData\Local\uv
C:\Users\用户名\AppData\Roaming\uv
C:\Users\用户名\.local\bin

修改uv目录

setx UV_HOME "D:\Program\Work\uv" # 替换为安装时选择的目录
setx UV_CACHE_DIR "%UV_HOME%\cache"
setx UV_CONFIG_FILE "%UV_HOME%\uv.toml"
setx UV_INSTALL_DIR "%UV_HOME%\bin"
setx UV_PYTHON_BIN_DIR "%UV_HOME%\bin"
setx UV_PYTHON_CACHE_DIR "%UV_HOME%\cache"
setx UV_PYTHON_INSTALL_DIR "%UV_HOME%\python"
setx UV_TOOL_BIN_DIR "%UV_HOME%\bin"
setx UV_TOOL_DIR "%UV_HOME%\tools"

环境变量-用户变量-path，添加D:\Program\Work\uv\bin

3. 换源

创建D:\Program\Work\uv\uv.toml

python-install-mirror = "https://gitproxy.click/https://github.com/indygreg/python-build-standalone/releases/download"

4. 安装工具

安装工具

uv tool install ruff@latest

5. 创建项目

创建项目文件夹，pycharm打开，terminal执行

uv init # 项目初始化
uv python install 3.13 # 安装指定版本
uv python pin 3.13 # 固定python版本

创建uv.toml

python-install-mirror = "https://gitproxy.click/https://github.com/indygreg/python-build-standalone/releases/download"

[[index]]
name = "tsinghua" # 清华源
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

[[index]]
name = "aliyun" # 阿里云源
url = "https://mirrors.aliyun.com/pypi/simple"

6. 开发

uv venv # 创建虚拟环境
uv add pandas # 安装依赖
uv remove pandas # 卸载依赖
uv run src\main.py # 运行项目
uv sync # 同步环境

uv build # 生成 sdist & wheel
uv publish # 上传到 PyPI（需 token）

五、uv命令总结

官方文档-命令：https://docs.astral.sh/uv/reference/cli/

命令	一句话说明	典型示例
`uv run`	在项目虚拟环境里执行任意命令或脚本	`uv run python main.py`
`uv init`	创建新的 Python 项目骨架	`uv init hello-world`
`uv add`	向项目添加依赖并写进 `pyproject.toml`	`uv add requests==2.31`
`uv remove`	从项目中移除依赖并同步 lock	`uv remove pandas`
`uv sync`	按 lock 文件把依赖装进 `.venv`	`uv sync --dev`
`uv lock`	生成/更新 `uv.lock` 锁定依赖	`uv lock --upgrade-package flask`
`uv export`	把 lock 文件导出为 requirements.txt 等	`uv export --format requirements.txt`
`uv tree`	可视化查看依赖树	`uv tree --depth 2`
`uv tool`	安装/运行全局 CLI 工具（类似 pipx）	`uv tool install ruff`
`uv python`	安装、切换、卸载 Python 解释器	`uv python install 3.12`
`uv pip`	与 pip 100% 兼容的接口	`uv pip install -e .`
`uv venv`	创建虚拟环境	`uv venv --python 3.11`
`uv build`	打包 wheel & sdist	`uv build`
`uv publish`	上传到 PyPI 或私有仓库	`uv publish`
`uv cache`	管理缓存（清、查看、改路径）	`uv cache clean`
`uv self`	升级或卸载 uv 自身	`uv self update`
`uv version`	读取或修改项目版本号	`uv version 1.2.3`
`uv help`	查看任意子命令帮助	`uv help sync`

后记

PyCharm 2024.3.2已经引入了对uv的支持，后续有时间重新安装一下pycharm最新版，再更新教程

PyCharm 2024.3.2 最新变化
在这里插入图片描述

参考文献

【AI总结】全网最全 2025 版！Python 九种解释器「全家福」超深度横评
 【AI总结】Python解释器全景解析：从CPython到GraalPython的深度对比
 uv安装python及其依赖的加速方法
 uv包管理器安装python的研究与本地镜像库搭建
 国内加速安装 uv Python 的终极方案：自建智能代理站
 2025年Python开发者必备的12大工具
 【AI总结】一篇吃透 Ruff CLI：从入门到进阶的完整命令手册
 uv中文文档

喜欢的点个关注吧><！祝你永无bug~

/*
                   _ooOoo_
                  o8888888o
                  88" . "88
                  (| -_- |)
                  O\  =  /O
               ____/`---'\____
             .'  \\|     |//  `.
            /  \\|||  :  |||//  \
           /  _||||| -:- |||||-  \
           |   | \\\  -  /// |   |
           | \_|  ''\---/''  |   |
           \  .-\__  `-`  ___/-. /
         ___`. .'  /--.--\  `. . __
      ."" '<  `.___\_<|>_/___.'  >'"".
     | | :  `- \`.;`\ _ /`;.`/ - ` : | |
     \  \ `-.   \_ __\ /__ _/   .-` /  /
======`-.____`-.___\_____/___.-`____.-'======
                   `=---='
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
            佛祖保佑       永无BUG
*/