[Python]：UV 使用与结合 PyCharm 的工作流

2401_87155481

970人浏览 · 2026-04-16 20:46:16

2401_87155481 · 2026-04-16 20:46:16 发布

uv 是一个 Python 虚拟环境管理工具，比 Anaconda 更轻量且效率高，适合简单 Python 脚本，以及 Agent 开发使用，本文将介绍 uv 下载、配置、使用，以及结合 PyCharm 的工作流

uv 官网：https://docs.astral.sh/uv/

一、下载与配置

很多同学安装 uv 后发现它还是往 C 盘塞东西。通过以下方法，可以将 uv 的主程序、Python 解释器库、缓存以及镜像源全部定向到 D 盘

(一) 目录结构规划

首先手动创建一个核心根目录，我们以 D:\Code\Python\UV 为例（作者是这样分区的，之后也以此为例，可自行更换 UV 文件夹前的目录结构），并在其下建立三个核心子文件夹：

bin：存放 uv 可执行程序
cache：存放所有包的缓存（这是占用空间最大的地方）
python：存放 uv 下载的各版本 Python 解释器

效果如下：

(二) 环境变量核心配置

这是最关键的一步，通过 Windows 用户环境变量进行重定向：

变量名	变量值 (示例)	作用
UV_PYTHON_INSTALL_DIR	D:\Code\Python\UV\python	强制 uv 将下载的 Python 解释器装到 D 盘
UV_CACHE_DIR	D:\Code\Python\UV\cache	强制将包缓存存入 D 盘
UV_DEFAULT_INDEX	https://pypi.tuna.tsinghua.edu.cn/simple	设置清华镜像源，加速下载
Path（添加项）	D:\Code\Python\bin	确保在任何目录下都能直接运行 uv 命令

效果如下：

注意：

Path 中的添加项，即 D:\Code\Python\bin，最好放在第一个，从而避免与其他 Python 冲突，如 Anaconda 中的 Python 环境，因为我们需要优先使用的是 uv
如果 Anaconda 还需要使用，可以单独在 Anaconda Prompt 中使用 Conda 语句，如下：

(三) 下载

以管理员身份运行 PowerShell，输入以下命令（自行替换 D:\Code\Python\UV\bin）

# 1. 在当前会话中明确指定安装目录（确保脚本知道去哪）
$env:UV_INSTALL_DIR = "D:\Code\Python\UV\bin"

# 2. 执行官方下载并安装脚本
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

$env:UV_INSTALL_DIR 说明: 官方安装脚本会检查这个变量。如果你不设置，它默认会去 C:\Users\用户名\.cargo\bin。设置后，它会直接把 uv.exe 和 uvx.exe 下载到你指定的 D:\Code\Python\UV\bin

可使用以下命令检查

# 1. 检查 uv
where.exe uv
# 2. 检查 cache
uv cache dir

效果应如下：

现在我们就完成 uv 下载和配置了

二、基本使用

1. 环境管理

uv 以“项目”为单位管理环境，他会为每个项目创建独立的 .venv 文件

创建新项目（自动初始化环境）

uv init my_project  # 这会创建一个文件夹，里面包含 Python 配置文件 
uv init             # 这会在当前文件夹创建项目

创建虚拟环境

uv venv               # 默认创建在当前目录的 .venv 文件夹
uv venv --python 3.9  # 指定 Python 版本

激活环境

使用 uv run 命令时，无需手动激活

查看依赖树

清晰展示包的层级关系：

uv tree

删除环境

直接删除项目下的 .venv 文件夹即可彻底清理

2. 包管理

安装与记录依赖

自动安装并记录到项目配置中：

uv add openai            # 安装最新版  
uv add openai==1.10.0    # 指定版本  
uv add --dev pytest      # 标记为开发依赖

卸载包

uv remove openai

同步环境
根据配置文件一键恢复环境状态：

uv sync # 根据配置文件，一键把环境恢复成规定状态

查询包信息

uv pip list          # 列出已安装包  
uv pip show package_name  # 查看包详情

3. Python 版本管理

这是 uv 杀手级的功能，它能直接管理电脑上的 Python 本身

列出电脑上（及官方库里）所有的 Python 版本：

uv python list

安装指定版本

它会乖乖装进你指定的 D:\Code\Python\UV\python 目录

uv python install 3.12

uv venv --python 3.10

4. 运行与执行

直接运行脚本

uv 会自动检查依赖是否装好，自动在环境里运行，你连 activate 都不用输入：

uv run main.py

临时运行工具

uvx 会下载、运行、然后清理，不占地方

uvx textual-paint

5. 配置与维护

查看缓存路径

uv cache dir

清理缓存

uv cache clean

更新工具自身

uv self update

6. uv 工作流（串联前文的 uv 命令）

我们将 uv 的工作流总结为 “初始化 -> 开发 -> 运行 -> 维护” 四个核心阶段

6.1. 项目启动（初始化）

每当你有一个新点子，比如想写个新 Agent 时：

1. 初始化项目：

uv init my_project (这会创建一个文件夹，里面包含 Python 配置文件)
uv init (这会在当前文件夹创建项目)

结果：它会生成 pyproject.toml（项目清单）和 hello.py
注意：此时还没创建虚拟环境，不用急

2. 创建虚拟环境：

uv venv (默认创建在当前目录的 .venv 文件夹)
uv venv --python 3.9 (指定 Python 版本)

6.2. 依赖管理（装包）

你想用什么功能，就“加”什么包：

1. 添加普通依赖（如 OpenAI SDK）：

uv add openai python-dotenv langchain

2. 添加开发依赖（如代码格式化工具，项目运行不需要，但写代码需要）：

uv add --dev ruff pytest

3. 移除包（可选）：

uv remove langchain

6.3. 代码运行（无需激活！）

这是 uv 最爽的地方，你永远不需要手动执行 activate 命令

1. 直接运行脚本：

uv run hello.py

原理：uv run 会自动识别当前目录下的 .venv，进去跑完代码，然后出来

2. 运行特定的 Python 命令：

uv run python -m some_module

6.4. 环境同步与协作（克隆别人的项目）

如果你从 GitHub 下载了一个别人的 Agent 项目，或者在另一台电脑上继续开发：

1. 一键还原环境：

uv sync

结果：uv 会读取 pyproject.toml，自动把 Python 版本和所有包安装得一模一样

6.5. Python 版本控制（按需切换）

如果你的 Agent 需要在特定版本下运行：

下载指定版本：uv python install 3.12
强制当前项目使用特定版本：

uv venv --python 3.12

6.6. 临时工具调用（uvx 魔法）

如果你只想临时用一个 Python 工具（比如想看一眼某个 JSON 文件，或者用某个爬虫工具），但不想把它装进你的项目里：

uvx some-tool-name

结果：uv 会创建一个临时环境运行它，运行完自动销毁，不占空间，不污染你的项目

以上就是 uv 的简单使用

三、uv + PyCharm 联合使用

PyCharm 在 Python 编程方面运用十分广泛，在这部分会介绍 uv 结合 PyCharm 的工作流（作者本人总结，可能有不足）

(一) 首先先介绍一下 Pycharm 中环境的选择

利用 PyCharm 新建项目时，有三种解释器选择，以下是说明

1. 项目 venv —— 最常用

含义：这是 Python 官方的标准虚拟环境。它是在你的项目文件夹里创建的一个独立的 .venv 文件夹
特点：
- 独立性：环境跟着项目走。删掉项目文件夹，环境也就没了
- 轻量：只包含运行该项目必需的包
与 uv 的关系：uv 也是为当前项目创建 .venv，但在使用上可跳过创建项目以及选择解释器步骤，具体见后文“uv + PyCharm 终极工作流（CLI 优先）”

2. 基础 conda —— Anaconda 的“新开户”

含义：这是让 PyCharm 调用 conda.exe 去创建一个全新的 Conda 虚拟环境
特点：
- 环境通常存储在你指定的 envs_dirs 目录下，而不是在项目文件夹里
- 你可以利用 Conda 强大的科学计算包管理能力
使用场景：你想为这个新项目创建一个全新的 Conda 环境时选它

3. 自定义环境 —— “老兵报道”

含义：这是指使用电脑上已经存在的 Python 解释器
特点：
- 复用性：如果已有配置好的虚拟环境，如 Conda 虚拟环境，而你现在的项目也想用这个，直接选它就行
使用场景：你想让新项目直接“套用”以前建好的 Conda 虚拟环境或全局 Python

(二) uv + PyCharm 终极工作流（CLI 优先）

这套流程的核心是：把环境管理的权力完全交给 uv，PyCharm 只需要闭着眼睛用

1. 第一步：在终端（CLI）一气呵成

不要在 PyCharm 的“新建项目”界面纠结，直接在 PowerShell 里操作：

uv init my_agent_project    # 1. 创建项目结构
cd my_agent_project         # 2. 进入目录
uv venv --python 3.13		# 3. 可省略
uv add openai langchain     # 4. 核心：这一步会自动创建 .venv 并安装包

2. 第二步：PyCharm 直接“拎包入住”

2.1 打开 PyCharm，点击 Open（不要点 New Project）

2.2 选中刚才的 my_agent_project 文件夹

2.3 PyCharm 的自动感应：

现在的 PyCharm 非常聪明。它看到目录下有 .venv 文件夹，通常会直接弹窗问你："Python virtual environment found. Do you want to use it?"
直接点 OK
如果它没弹窗，你只需要在右下角点击 Python 解释器，手动指向一次项目里的 .venv/Scripts/python.exe。全过程只需这一回
如下图，一般会自动识别到