环境管理

默认系统（mac）上安装 Python 3.14.0 版本

pyenv 安装与配置

使用 pyenv 来管理多个 Python 版本，这样你可以轻松地在不同项目中使用不同版本的 Python。

# 使用 Homebrew 安装 pyenv
brew install pyenv

# 编辑 zsh 配置文件
nano ~/.zshrc

# 在文件末尾添加：
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# 保存并退出（Ctrl+O → 回车 → Ctrl+X），然后重新加载配置：
source ~/.zshrec

# 安装 Python 3.11.0
pyenv install 3.11.0

# 查看已安装的 Python 版本
pyenv versions

# 设置 Python 版本 全局:
pyenv global 3.11.0

# 设置 Python 版本 项目级:
cd /path/to/your/project
pyenv local 3.11.0

# 验证安装
python --version

# 也可以随时切换回 3.14.0：
pyenv local 3.14.0
python --version  # 输出 Python 3.14.0

pipx 和 pip 对比

🔍 一、核心定位不同

工具	主要用途
`pip`	安装 Python 包到当前 Python 环境（全局或虚拟环境），用于开发或运行代码。
`pipx`	专门用于安装和运行 Python 命令行工具（CLI 工具），每个工具都隔离在独立的虚拟环境中。

✅ 简单说：

你想在项目中用 requests？→ 用 pip

你想在终端用 black、ruff、pdm、uv 这些命令？→ 用 pipx

📦 二、安装方式与环境隔离对比

特性	`pip`	`pipx`
是否隔离环境	❌ 默认不隔离（除非手动激活虚拟环境）	✅ 自动为每个工具创建独立虚拟环境
安装位置	当前 Python 环境的 `site-packages`	`~/.local/pipx/venvs/<package>/`
是否污染全局环境	✅ 容易（尤其用 `pip install --user` 或全局安装）	❌ 不会，完全隔离
可否同时安装多个版本？	❌ 困难	✅ 理论上可以（需手动管理）

示例说明：

# 使用 pip 安装 ruff（全局）
pip install ruff

ruff 被安装到当前 Python 环境的 site-packages
如果该环境已有其他依赖冲突，可能出错
多个项目共用，容易版本冲突

# 使用 pipx 安装 ruff
pipx install ruff

pipx 自动创建一个独立虚拟环境 ~/.local/pipx/venvs/ruff/
所有 ruff 的依赖都安装在这个环境中
不影响系统或其他工具
你可以在任何地方运行 ruff 命令

🛠 三、使用方式对比

场景	`pip`	`pipx`
安装包供项目使用	✅ `pip install requests`	❌ 不适合
安装 CLI 工具（如 `black`, `ruff`）	⚠️ 可以，但易冲突	✅ 推荐方式
运行一次性命令	❌ 不支持	✅ `pipx run black --version`
升级工具	`pip install --upgrade black`	`pipx upgrade black`
列出已安装工具	`pip list`（显示所有包）	`pipx list`（只显示 CLI 工具）
卸载	`pip uninstall black`	`pipx uninstall black`

💡 pipx run 是一个强大功能：你可以临时运行一个工具而无需安装：
pipx run black --version  # 临时下载并运行 black

🧩 四、典型使用场景

✅ 应该用 `pip` 的情况：

在项目中安装依赖：pip install django
在虚拟环境中安装包：venv/bin/pip install numpy
构建自己的库或应用

✅ 应该用 `pipx` 的情况：

安装开发工具：pipx install black ruff pdm uv poetry
安装命令行脚本：pipx install httpx
临时运行一个工具：pipx run mkdocs serve

🔄 五、是否互斥？可以共存吗？

✅ 完全可以共存，而且推荐搭配使用：

# 1. 用 pipx 安装现代工具（安全、隔离）
pipx install pdm
pipx install uv
pipx install ruff

# 2. 用这些工具来管理你的项目
pdm init
pdm add requests

# 3. 在项目内部，pdm 或 uv 会使用 pip（或 uv）来安装依赖

📌 最佳实践：用 pipx 安装工具，用工具管理项目依赖

✅ 总结：`pip` vs `pipx` 安装依赖的区别

对比项	`pip`	`pipx`
目的	安装库供代码使用	安装 CLI 工具供命令行使用
环境隔离	无（除非手动管理）	自动隔离（每个工具独立虚拟环境）
是否推荐用于全局安装	❌ 不推荐（易冲突）	✅ 强烈推荐
适合安装 `black` 吗？	可以，但有风险	✅ 最佳方式
适合安装 `requests` 吗？	✅ 是	❌ 不适合（除非你写了个叫 `requests` 的 CLI 工具）
性能	快	稍慢（因为要创建虚拟环境），但值得

🎯 一句话总结：

pip 是用来安装“库”的，pipx 是用来安装“命令”的。

你要在代码里 import requests？→ 用 pip
你要在终端运行 ruff .？→ 用 pipx

这样用，你的 Python 环境才会干净、安全、高效。

包管理工具 uv 安装与使用

uv 是一个用 Rust 编写的高性能 Python 包安装器、依赖解析器和虚拟环境管理器，由开发 Ruff（超快 Python linter）的公司 Astral 推出。

它旨在替代 pip、virtualenv 和 pip-tools，速度极快（号称比 pip 快 10-100 倍）。
支持现代 Python 打包标准（PEP 508, PEP 621 等）
可作为 pip + venv 的现代化替代品

🔧 安装和用法

pipx install uv  # 推荐

初始化项目：uv init
安装包并自动添加到 pyproject.toml 中：uv add [--dev] requests
安装包：uv install requests
安装依赖文件：uv install -r requirements.txt
创建虚拟环境：uv venv .venv
从 pyproject.toml 项目同步依赖：uv sync

📦 uv 索引源配置

在使用 uv 时，你可以通过配置 index URLs（索引源） 来从不同的源（如国内镜像源）下载 Python 包，这在访问 PyPI 官方源较慢时非常有用（例如在中国大陆地区）。

uv 支持与 pip 兼容的索引源配置方式，可以通过命令行参数或配置文件指定自定义源。

一、使用命令行参数指定源

使用 --index-url 指定主源（替换 PyPI）

uv install requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple

这会从 清华大学镜像源 下载 requests 及其依赖。

使用 --extra-index-url 添加额外源（保留 PyPI，但优先使用镜像）

uv install requests --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple

优先从指定镜像源查找包
如果找不到，会回退到默认的 PyPI 源
更安全，避免某些私有包或新包在镜像中未同步的问题

同时使用多个额外源

uv install requests \
  --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple \
  --extra-index-url https://pypi.douban.com/simple

二、使用配置文件（推荐长期使用）

uv 支持通过配置文件设置默认的索引源，避免每次手动输入。

使用 pyproject.toml（项目级配置）

在项目根目录的 pyproject.toml 中添加：

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
extra-index-urls = [
    "https://pypi.org/simple"
]

这样，uv install 会默认使用清华源。

使用全局配置文件

uv 的全局配置文件路径（取决于系统）：

macOS: ~/Library/Application Support/uv/config.toml
Linux: ~/.config/uv/config.toml
Windows: %APPDATA%\uv\config.toml

在 config.toml 中添加：

[index]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"

或使用额外源：

[extra-index]
urls = ["https://pypi.tuna.tsinghua.edu.cn/simple"]

⚠️ 注意：uv 目前仍在快速迭代，配置文件格式可能略有变化，请参考官方文档。

三、常用国内镜像源（可替换 URL）

镜像源	URL
清华大学	`https://pypi.tuna.tsinghua.edu.cn/simple`
阿里云	`https://mirrors.aliyun.com/pypi/simple`
中国科学技术大学	`https://pypi.mirrors.ustc.edu.cn/simple`

四、验证是否生效

你可以通过 --verbose 查看详细日志：

uv install requests --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple --verbose

在输出中你会看到类似：

Fetching: https://pypi.tuna.tsinghua.edu.cn/simple/requests/

说明正在从指定源下载。

五、注意事项

安全性：确保你信任所使用的镜像源，避免恶意包。
同步延迟：镜像源可能比官方 PyPI 延迟几分钟到几小时。
私有包：如果你使用私有包索引，也可以用 --index-url 指向私有仓库（如 Nexus、Artifactory）。
兼容性：uv 的索引参数与 pip 基本兼容，习惯 pip 的用户可以无缝迁移。

uv 不会自动读取 pip.conf 或 pip.ini，即使你已经为 pip 配置了镜像源，uv 仍会使用默认的 PyPI。

所以你需要单独为 uv 配置，或者在命令行中指定。

💡 推荐：在中国大陆地区开发时，使用 --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple 以获得最佳下载速度。

`uv install` 和 `uv add`

uv add 是 项目模式（project mode） 下的命令，用于声明式管理依赖，会自动将包写入 pyproject.toml。
uv install 是 环境模式（environment mode） 下的命令，用于直接安装包，不会修改 pyproject.toml。

📚 详细对比

特性	`uv add requests`	`uv install requests`
是否修改 `pyproject.toml`	✅ 是，自动添加到 `[project.dependencies]`	❌ 否，不修改任何文件
是否需要 `pyproject.toml`	✅ 是，必须在项目目录中或已初始化	❌ 否，可在任意 Python 环境使用
设计用途	声明式依赖管理（类似 `npm install pkg`）	直接安装包（类似 `pip install pkg`）
是否生成 lock 文件	✅ 是，更新 `uv.lock`	✅ 是，也会生成/更新 `uv.lock`（如果在项目中）
推荐使用场景	现代 Python 项目开发（推荐）	快速测试、脚本环境、非项目场景
类比工具	`npm add`, `poetry add`, `pdm add`	`pip install`, `npm install --save-dev`（旧方式）

🛠 `--dev` 选项的区别

uv add --dev pytest

将 pytest 添加到 pyproject.toml 的开发依赖中（如 [project.optional-dependencies.dev]）
下次运行 uv sync --group dev 会自动安装

uv install --dev pytest

❌ uv install 不支持 --dev 标志！
如果你运行 uv install --dev pytest，会报错：error: The argument '--dev' cannot be used with 'install'

⚠️ 这是关键区别：--dev 只在 uv add 和 uv sync 中有意义，因为它是项目依赖分组的概念，而 install 不管理项目结构。

🧩 补充说明：uv install 的 --dev 是什么？

你可能会看到 uv install --dev .，这里的 --dev 不是指“开发依赖”，而是指 “以可编辑模式安装当前项目”。

uv install --dev .

# 等价于：
pip install -e .

表示安装当前项目本身（作为可编辑包），常用于开发库。

而 uv add --dev 中的 --dev 是指 依赖分组（dev-dependencies），两者完全不同。

包管理工具 PDM 安装与配置

使用 pipx（推荐用于全局安装）

# 全局安装
pipx install pdm

# 验证安装
pdm --version

初始化配置（可选）

pdm config --list

开始使用

# 初始化 PDM
pdm init

# 添加依赖
pdm add requests
pdm add -d pytest  # 作为开发依赖

# 运行脚本
pdm run python your_script.py

通过 scripts 快捷启动

你可以在 pyproject.toml 中定义快捷命令，方便启动项目。

添加启动脚本

编辑 pyproject.toml，添加 [tool.pdm.scripts] 部分：

[tool.pdm.scripts]
start = "python app.py"
dev = "python app.py --debug"
test = "pytest"
lint = "flake8 ."
format = "black ."

使用方式

pdm run start   # 相当于 pdm run python app.py
pdm run dev     # 启动调试模式
pdm run test    # 运行测试
pdm run lint    # 检查代码风格

`pdm shell` 报错

PDM 版本（2.26.0）中 shell 命令已经被移除了。

# 查看可用的虚拟环境
pdm venv list

# 1. 创建虚拟环境
pdm venv create

# 激活虚拟环境（假设使用默认的venv）
pdm venv activate
# 或者：
source .venv/bin/activate  # Linux/Mac
# 或者 Windows: .venv\Scripts\activate

pyproject.toml 配置 PDM 脚本命令

[tool.pdm.scripts]

app.cmd = "python app/main.py"    # 执行的命令
app.env_file = ".env"             # 加载的环境变量文件

运行这个脚本: pdm run app

当你运行 pdm run app 时，PDM 会：

加载环境变量：首先从 .env 文件读取所有环境变量
执行命令：然后运行 python app/main.py
使用虚拟环境：自动使用当前项目的虚拟环境中的 Python 解释器

启动常见 Web 框架示例

FastAPI / Starlette（使用 Uvicorn）

[tool.pdm.scripts]
start = "uvicorn app:app --reload --host 0.0.0.0 --port 8000"

Flask

[tool.pdm.scripts]
start = "flask --app app run --debug --port 5000"

或者：

[tool.pdm.scripts]
start = "python app.py"

在 app.py 中：

if __name__ == "__main__":
    app.run(debug=True, port=5000)

Django

[tool.pdm.scripts]
runserver = "python manage.py runserver 8000"
migrate = "python manage.py migrate"

pdm run runserver

查看当前 Python 和环境

cd /path/to/project
pdm info

输出示例：

PDM version:
  2.26.0
Python Interpreter:
  /Users/houfei/Desktop/labelllm/backend/.venv/bin/python (3.11)
Project Root:
  /Users/houfei/Desktop/labelllm/backend
Local Packages:
  /Users/houfei/Desktop/labelllm/backend/.venv/lib/python3.11/site-packages

指定 Python 版本

pdm use 3.11
# 或
pdm use /usr/bin/python3.11

pyenv 安装与配置​

pipx 和 pip 对比​

🔍 一、核心定位不同​

📦 二、安装方式与环境隔离对比​

🛠 三、使用方式对比​

🧩 四、典型使用场景​

✅ 应该用 pip 的情况：​

✅ 应该用 pipx 的情况：​

🔄 五、是否互斥？可以共存吗？​

✅ 总结：pip vs pipx 安装依赖的区别​

🎯 一句话总结：​

包管理工具 uv 安装与使用​

🔧 安装和用法​

📦 uv 索引源配置​

一、使用命令行参数指定源​

二、使用配置文件（推荐长期使用）​

三、常用国内镜像源（可替换 URL）​

四、验证是否生效​

五、注意事项​

uv install 和 uv add​

📚 详细对比​

🛠 --dev 选项的区别​

包管理工具 PDM 安装与配置​

使用 pipx（推荐用于全局安装）​

初始化配置（可选）​

开始使用​

通过 scripts 快捷启动​

pdm shell 报错​

pyproject.toml 配置 PDM 脚本命令​

启动常见 Web 框架示例​

查看当前 Python 和环境​