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

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 用户环境变量进行重定向：

效果如下：

注意：

• 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

• 在当前目录临时切换 Python 版本

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 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。全过程只需这一回
• 如下图，一般会自动识别到