🧩 UV 使用与环境管理指南

📖 概览

uv 是一个现代的 Python 项目管理工具，负责管理 Python 版本、虚拟环境、依赖安装、锁文件同步，并在正确的环境中运行项目。

🗂️ 各文件与目录的用途

文件 / 目录 作用 说明
pyproject.toml 项目配置文件 声明项目名称、Python 版本范围、依赖等。
uv.lock 依赖锁文件 记录每个包的精确版本，保证环境可复现。
.python-version 固定 Python 版本 通过 uv python pin 3.12 生成，指定项目解释器。
.venv/ 虚拟环境目录 存放项目依赖包与执行入口。
~/.local/share/uv/python/ 全局解释器仓库 存放 uv 管理的 Python 版本本体。

⚙️ uv run 的环境解析逻辑

  1. 定位项目根目录（查找 pyproject.toml / .venv/）。
  2. 选择虚拟环境（优先 .venv/，否则自动创建）。
  3. 选择 Python 版本：
    • .python-version → pyproject.toml 的 requires-python → 自动安装/选择。
  4. 按 uv.lock 同步依赖。
  5. 在确定的环境与解释器中执行命令。

🔗 .venv 与解释器的关系

~/.local/share/uv/python/3.12.4/   ← 解释器本体
└── linked by ───►  .venv/bin/python  ← 启动器
.venv/lib/python3.12/site-packages/  ← 项目依赖包

检查当前环境：

uv run python -c "import sys, site; print(sys.executable); print(sys.version); print(site.getsitepackages())"

🪜 初次使用流程

新建项目

cat > pyproject.toml <<'EOF'
[project]
name = "myproj"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = []
EOF

uv python pin 3.12
uv add requests numpy
uv run main.py

已有项目

uv sync
uv run main.py

使用 requirements.txt

uv venv
uv pip install -r requirements.txt
# 或迁移为 uv 项目
uv add -r requirements.txt

📦 常用命令

# 🧩 UV 使用与环境管理指南 功能
## 📖 概览uv add package 安装依赖并写入 pyproject 与锁文件
uv 是一个现代的 Python 项目管理工具，负责管理 Python 版本、虚拟环境、依赖安装、锁文件同步，并在正确的环境中运行项目。uv pip install -r req.txt 按 requirements 安装，不更新配置
## 🗂️ 各文件与目录的用途uv sync 按锁文件同步环境
文件 / 目录 作用
## ⚙️ uv run 的环境解析逻辑uv run 在正确环境中运行项目
1. 定位项目根目录（查找 pyproject.toml / .venv/）。uv python pin 3.12 固定解释器版本
2. 选择虚拟环境（优先 .venv/，否则自动创建）。uv python dir 显示解释器仓库路径

✅ 总结

  • .venv 保存依赖和入口；解释器本体在 ~/.local/share/uv/python/。
  • .python-version 固定版本；pyproject.toml 声明依赖；uv.lock 锁定版本。
  • uv sync 同步环境；uv run 在正确环境中执行。