环境管理

适用环境：macOS（Apple Silicon，Homebrew 路径 /opt/homebrew；Intel Mac 对应路径为 /usr/local），终端使用 zsh。

Homebrew

安装 Python / pyenv

brew update
brew install python        # 安装最新稳定版
brew install python@3.12   # 安装指定版本

包名是 python 或 python@3.x，不是 python3。brew install python3 / brew upgrade python3 会报 not installed。

多版本管理推荐使用 pyenv：

brew install pyenv

Homebrew 换源

brew update / brew install 慢，通常是 GitHub 访问不稳定导致。写入 ~/.zshrc（清华 TUNA）：

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"

或使用中科大 USTC 镜像：

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"

生效并验证：

source ~/.zshrc
brew config | grep -E "HOMEBREW_BREW_GIT_REMOTE|HOMEBREW_API_DOMAIN|HOMEBREW_BOTTLE_DOMAIN"

注意事项：

• 不要随意设置 HOMEBREW_CORE_GIT_REMOTE。新版 Homebrew 默认走 API，镜像也不再推荐用 homebrew-core.git。
• 临时跳过安装时的自动更新：HOMEBREW_NO_AUTO_UPDATE=1 brew install xxx（不建议长期禁用，索引会变旧）。

常见卡顿对照：

现象	原因 / 处理
卡在 Downloading Homebrew API data	HOMEBREW_API_DOMAIN 未生效
卡在 Downloading xxx--....bottle	HOMEBREW_BOTTLE_DOMAIN 未生效
提示 --build-from-source	源码编译慢，优先让 bottle 走镜像
新开终端窗口后失效	重新 source ~/.zshrc
挂了代理仍慢	可临时关闭代理再试

卸载 Homebrew 安装的 Python

先查已安装版本，再卸载指定版本：

brew list | grep python
brew uninstall python@3.14
brew cleanup -s python@3.14

若报「required by pipx」拒绝卸载（被其它包依赖）：

# 方案一：连同依赖一起卸载（不需要 pipx 时，最干净）
brew uninstall pipx
brew uninstall python@3.14

# 方案二：强制忽略依赖（pipx 会失效，之后用 brew install pipx 重装）
brew uninstall --ignore-dependencies python@3.14

清理残留：

rm -rf ~/Library/Python/3.14
rm -rf ~/.local/bin/pip3*

⚠️ 不要删除 /usr/bin/python3（macOS 系统自带）。卸载 Homebrew Python 后，python3 通常会自动指向系统自带或剩余版本。

---

pyenv

pyenv 是专门管理 Python 版本切换的工具。

安装与初始化

brew install pyenv

安装 pyenv 编译 Python 所需的系统依赖：

xcode-select --install          # 安装 Command Line Tools
brew install openssl readline sqlite3 xz zlib tcl-tk

在 ~/.zshrc 末尾添加：

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"

重新加载并验证：

source ~/.zshrc
pyenv --version

常用命令

pyenv install --list    # 查看可安装版本
pyenv install 3.12.7    # 安装指定版本
pyenv versions          # 查看已安装版本（* 为当前生效版本）
pyenv global 3.12.7     # 设置全局默认版本
pyenv local 3.10.13     # 在项目目录设置版本（写入 .python-version）
pyenv shell 3.11.9      # 仅当前终端会话生效
pyenv global system     # 恢复使用系统自带 Python
pyenv uninstall 3.12.7   # 卸载版本
pyenv which python      # 查看实际指向的解释器路径
pyenv rehash            # 安装新版本或装了带命令的程序后刷新 shim

作用域优先级：shell > local > global。

pyenv 通过 shim 接管 python / python3，确保 PATH 中 $PYENV_ROOT/shims 在最前。

卸载 pyenv

rm -rf ~/.pyenv   # 删除 pyenv 及所有已安装版本
brew uninstall pyenv
# 同时删除 ~/.zshrc 中的 pyenv 初始化配置，再 source ~/.zshrc

pyenv install 慢的解决方法

pyenv install 慢主要有两类原因：下载源码慢 和 本地编译慢。

1. 下载慢 —— 换镜像源

# npmmirror（阿里）镜像，写入 ~/.zshrc
export PYTHON_MIRROR="https://npmmirror.com/mirrors/python/"

写入后 source ~/.zshrc 再安装。

2. 编译慢 —— 复用预编译二进制

使用 pbx 插件复用 Homebrew 的预编译产物，跳过本地编译：

brew install pbx
pbx install 3.12.7

3. 编译报错 —— 补齐依赖与头文件路径

brew install openssl readline sqlite3 xz zlib tcl-tk
export LDFLAGS="-L/opt/homebrew/opt/openssl@3/lib -L/opt/homebrew/opt/readline/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl@3/include -I/opt/homebrew/opt/readline/include"
pyenv install 3.12.7

4. 安装卡住排查

pyenv install -v 3.12.7        # -v 显示详细过程，定位卡点

• 卡在下载阶段 → 检查 PYTHON_MIRROR 是否生效。
• 卡在编译阶段 → 走 pbx 预编译，或确认 Command Line Tools 已安装、依赖齐全。

---

pip 与 pipx

pip 用来给项目装库，pipx 用来给终端装工具；两者是互补关系，不是替代关系。

维度	pip	pipx
定位	通用 Python 包安装器	专门管理 Python CLI 工具
安装对象	库、模块、应用	带命令行入口的应用
安装位置	当前 Python 环境	每个工具一个独立 venv
环境隔离	无，需配合 venv	自动隔离
全局可用	不一定	自动链接到 PATH
典型命令	pip install requests	pipx install black
能否 import	能	不能
适用场景	项目依赖	全局命令行工具

简单记：代码里要 import 的用 pip，终端里直接敲命令的用 pipx。

推荐组合

# 1. 全局环境只装 pipx
python -m pip install --user pipx
pipx ensurepath

# 2. 命令行工具用 pipx
pipx install black
pipx install httpie

# 3. 项目依赖用 venv + pip
cd my_project
python -m venv .venv
source .venv/bin/activate
pip install flask requests

pip 换源

临时使用：

pip3 install 包名 -i https://pypi.tuna.tsinghua.edu.cn/simple

永久配置（推荐）：

pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

或手动写入 ~/.pip/pip.conf：

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

---

uv

uv 是用 Rust 编写的超快速 Python 包与项目管理器，可一站式替代 pip、pipx、pip-tools、poetry、pyenv、venv 等工具链，安装速度比 pip 快 10–100 倍。

安装

brew install uv

常用命令

uv init                  # 初始化项目
uv add requests          # 添加依赖并写入 pyproject.toml
uv add --dev pytest      # 添加开发依赖
uv sync                  # 按 uv.lock 同步项目环境
uv pip install requests  # pip 兼容接口：直接装包，不改动 pyproject.toml
uv pip install -r requirements.txt
uv venv .venv            # 创建虚拟环境
uv run main.py           # 在项目环境中运行脚本
uv python install 3.12   # 安装指定 Python 版本（替代 pyenv）
uvx ruff check .         # 临时运行 CLI 工具（替代 pipx run）

镜像源配置

访问 PyPI 官方源较慢时（例如在中国大陆），可通过参数或配置文件指定索引源。

命令行临时指定：

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

项目级配置（pyproject.toml）：

[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true  # 替换默认的 PyPI 源

全局配置（~/.config/uv/uv.toml）：

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

常用国内镜像源：

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

验证是否生效：

uv pip install requests --default-index https://pypi.tuna.tsinghua.edu.cn/simple --verbose
# 输出中出现 Fetching: https://pypi.tuna.tsinghua.edu.cn/simple/... 即说明生效

uv add 与 uv pip install 的区别

命令	模式	是否修改 pyproject.toml	典型场景
uv add [--dev]	项目模式	是（写入依赖或依赖分组）	管理项目依赖
uv pip install	环境模式	否	临时装包、安装 requirements.txt

• --dev 是依赖分组概念，只在项目模式有意义：uv add --dev pytest 会把 pytest 写入 [dependency-groups] 的 dev 分组，uv sync 默认会安装该分组。
• 以可编辑模式安装当前项目时，使用 uv pip install -e .。

---

附：常用验证命令速查

brew config                   # 查看 Homebrew 镜像配置
brew list | grep python       # 查看已装 Python
which -a python3              # 查看所有 python3 路径及优先级
python3 --version             # 查看当前版本
pyenv versions                # 查看 pyenv 已装/生效版本
pip3 config list              # 查看 pip 镜像配置