Python01_Python环境搭建

第一章：UV 工具概述

1.1 什么是 UV？

UV 是由 Astral 团队开发的极速 Python 包和项目管理工具，使用 Rust 语言编写。

核心特性：

• ⚡ 极速：比 pip 快 10-100 倍
• 🛠️ 全能：单一工具替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等
• 📦 项目管理：提供通用的 lockfile 机制
• 🐍 Python 版本管理：内置多版本 Python 管理能力

GitHub 地址： https://github.com/astral-sh/uv

1.2 参考资源

• UV 官方文档
• UV 快速开始指南
• pyproject.toml 使用指导
• UV 使用指南

---

第二章：UV 安装与配置

2.1 安装 UV

Windows 安装：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS 和 Linux 安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

2.2 核心概念对比

传统工具	UV 替代方案	用途
pip + virtualenv	uv venv	虚拟环境管理
pip-tools	uv pip compile	依赖锁定
poetry/pdm	uv init / uv add	项目管理
pyenv	uv python install	Python 版本管理
pipx	uvx	工具运行

---

第三章：Python 多版本管理

3.1 安装指定 Python 版本

方式一：创建环境时指定版本

uv venv --python 3.12.0

方式二：命令行直接运行

uv run --python pypy@3.8 -- python

方式三：固定项目 Python 版本

uv python pin 3.11

3.2 安装多个 Python 版本

uv python install 3.10 3.11 3.12

3.3 版本管理原理

• UV 会自动下载并管理不同版本的 Python 解释器
• 通过 .python-version 文件记录项目使用的 Python 版本
• 支持 CPython 和 PyPy 等多种解释器

---

第四章：项目依赖管理

4.1 创建新项目

创建项目目录：

uv init hello-world
cd hello-world

或在现有目录初始化：

mkdir hello-world
cd hello-world
uv init

生成的项目结构：

.
├── .python-version      # Python 版本锁定
├── README.md           # 项目说明
├── main.py             # 入口文件（示例代码）
└── pyproject.toml      # 项目配置和依赖

4.2 完整项目结构

首次运行项目命令（uv run、uv sync 或 uv lock）后，UV 会创建虚拟环境和 lockfile：

.
├── .venv/                 # 虚拟环境目录
│   ├── bin/              # 可执行文件
│   ├── lib/              # 安装的包
│   └── pyvenv.cfg        # 环境配置
├── .python-version       # Python 版本
├── README.md
├── main.py
├── pyproject.toml        # 项目元数据和依赖
└── uv.lock              # 依赖锁定文件（精确版本）

4.3 管理依赖

添加依赖：

# 添加最新版本
uv add requests

# 指定版本约束
uv add 'requests==2.31.0'

# 添加 Git 依赖
uv add git+https://github.com/psf/requests

移除依赖：

uv remove requests

升级依赖：

# 升级特定包
uv lock --upgrade-package requests

# 升级所有包
uv lock --upgrade

4.4 pyproject.toml 配置示例

[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=23.0",
]

---

第五章：运行与构建

5.1 运行项目

自动同步并运行：

uv run main.py

运行带参数的命令：

uv add flask
uv run -- flask run -p 3000

UV 的运行机制：

1. 检查 pyproject.toml 是否有变更
2. 如有变更，自动更新 uv.lock
3. 检查虚拟环境是否同步
4. 在隔离环境中执行命令

5.2 手动同步环境

# 同步环境（根据 uv.lock 安装依赖）
uv sync

# 激活虚拟环境（传统方式）
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# 然后直接运行
python main.py

5.3 构建发行版

# 构建源分发包和二进制 wheel
uv build

# 查看构建产物
ls dist/
# 输出: hello-world-0.1.0.tar.gz  hello_world-0.1.0-py3-none-any.whl

---

第六章：UVX 工具运行

6.1 UVX 与 UV 的关系

uvx 是 uv tool run 的别名（alias），用于在临时环境中运行 Python 工具。

等价关系：

uvx python script.py
# 等价于
uv run python script.py

6.2 UVX 的优势

• 简洁：减少输入字符，提高操作效率
• 临时环境：无需显式创建虚拟环境即可运行工具
• 隔离：避免工具依赖污染项目环境

6.3 使用场景

运行代码检查工具：

uvx black main.py
uvx flake8 .
uvx mypy main.py

运行一次性脚本：

uvx python -c "print('Hello, UV!')"

---

第七章：常见问题与解答（Q&A）

Q1：UV 与 pyproject.toml 是什么关系？

A：

• 无直接绑定关系：UV 是环境管理工具，pyproject.toml 是项目配置文件
• 可协同工作：UV 能读取 pyproject.toml 中的依赖定义并安装
• 标准兼容：UV 遵循 PEP 518/621 标准，与 Poetry、PDM 等工具配置兼容

工作流程示例：

# 1. UV 创建虚拟环境
uv venv my_env

# 2. 激活环境
source my_env/bin/activate

# 3. 根据 pyproject.toml 安装依赖（如使用 poetry）
poetry install

---

Q2：UV 与 Anaconda 的版本管理有什么区别？

对比项	UV	Anaconda
核心定位	轻量级虚拟环境 + 包管理	完整数据科学发行版
Python 版本管理	支持多版本安装和切换	强大的 conda 版本管理
磁盘占用	极小（仅必要工具）	较大（预装大量科学计算库）
包管理	基于 pip 标准	conda 包管理 + pip 混合
预装库	无	NumPy, Pandas, Matplotlib 等
适用场景	Web 开发、通用 Python 项目	数据科学、机器学习、科研
跨平台	支持 Win/Linux/macOS	支持 Win/Linux/macOS

选择建议：

• 选 UV：追求极速、轻量，做 Web 开发或通用项目
• 选 Anaconda：从事数据分析、AI/ML，需要预装科学计算库

---

Q3：uvx 和 uv run 有什么区别？

A：

• 功能等价：uvx 是 uv tool run 的别名，与 uv run 功能相同
• 使用差异：
  • uv run：在项目环境中运行，依赖项目配置
  • uvx：更常用于运行临时工具，语法更简洁

对比示例：

# 项目开发（使用 uv run）
uv run python manage.py runserver

# 临时运行工具（使用 uvx）
uvx black main.py
uvx pytest

---

Q4：UV 如何管理依赖锁定？

A： UV 使用 uv.lock 文件实现确定性依赖管理：

1. pyproject.toml：定义直接依赖和版本约束（较宽松）
2. uv.lock：记录精确版本和子依赖（严格锁定）

锁定机制：

# 生成/更新 lockfile
uv lock

# 同步环境到 lockfile 状态
uv sync

# 升级特定包并更新 lock
uv lock --upgrade-package requests

优势：

• 确保团队成员环境一致
• 可复现的构建
• 避免依赖冲突

---

Q5：UV 是否兼容现有的 pip 工作流？

A： 完全兼容！UV 提供 uv pip 子命令作为 pip 的直接替代：

# 替代 pip install
uv pip install requests

# 替代 pip freeze
uv pip freeze > requirements.txt

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

# 替代 pip compile（需要安装 uv）
uv pip compile requirements.in -o requirements.txt

迁移建议：

• 现有项目可逐步迁移，无需一次性改造
• 新项目建议直接使用 uv init 和 pyproject.toml 工作流

---

第八章：最佳实践

8.1 项目初始化流程

# 1. 创建项目
uv init my-project
cd my-project

# 2. 固定 Python 版本
uv python pin 3.11

# 3. 添加依赖
uv add fastapi uvicorn
uv add --dev pytest black

# 4. 开发运行
uv run main.py

# 5. 锁定依赖
uv lock

8.2 团队协作规范

1. 提交到版本控制：

   • ✅ pyproject.toml（必须）
   • ✅ uv.lock（推荐，确保一致性）
   • ✅ .python-version（推荐）
   • ❌ .venv/（必须加入 .gitignore）

2. 新成员入职：

   git clone <repo>
   cd project
   uv sync  # 自动安装所有依赖
   uv run main.py
   

8.3 性能优化技巧

# 使用缓存加速（UV 默认启用）
export UV_CACHE_DIR=/path/to/cache

# 并行安装（默认行为）
uv pip install -r requirements.txt

# 离线模式（使用缓存）
uv pip install --offline package-name

---

附录：常用命令速查表

命令	功能
uv init	初始化新项目
uv venv	创建虚拟环境
uv python install 3.11	安装 Python 版本
uv python pin 3.11	固定项目 Python 版本
uv add <pkg>	添加依赖
uv remove <pkg>	移除依赖
uv run <cmd>	在环境中运行命令
uvx <cmd>	快捷运行命令
uv sync	同步环境到 lockfile
uv lock	生成/更新锁定文件
uv build	构建发行包
uv pip install	pip 兼容模式安装

---

总结： UV 是现代 Python 开发的利器，通过统一工具链解决了传统 Python 环境管理的碎片化问题。建议在新项目中优先采用 UV，享受极速开发和一致的环境管理体验。

---

Python-UV常用脚本补充

# 1-uv环境搭建(指定版本，增删改查)
uv python list
uv python pin 3.11.4
uv init lightrag3_11_4 && cd lightrag3_11_4
uv venv && source .venv/bin/activate
uv add python-dotenv pydantic requests==2.31.0
uv remove requests
uv run main.py

# 2-uv安装requirements.txt
uv python pin 3.11.4
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
uv add -r requirements.txt


# 3-uv存量代码
cd XXXXX
uv python list
uv python pin 3.11.4
rm -rf .venv # 先把环境清理掉，有时候我们需要调整我们需要的Python版本
uv venv && source .venv/bin/activate  # 重新创建python环境
uv sync  # 把项目代码下载下来


# 4-运行flask
uv add flask
uv run -- flask run -p 3000

python flask run -p 3000
python main.py