MacOS 上应通过 pyenv 管理多 Python 版本，并为每个项目创建独立虚拟环境，配合 pip-tools 或 poetry 锁定依赖；严禁使用 pip install --user 或直接操作系统 Python，以确保解释器与包严格隔离。

MacOS 上管理多个 Python 版本及其对应依赖包，核心是避免系统 Python、Homebrew Python 和用户自装 Python（如 pyenv）之间的包冲突。关键不在于“能不能装多个版本”，而在于“每个版本的包是否只对它自己生效”——这靠的是 解释器路径隔离 和 虚拟环境绑定，不是单纯靠 pip install。

用 pyenv 管理 Python 版本，不碰系统 Python

macOS 自带的 /usr/bin/python3 是系统组件，不应 pip install 任何第三方包。Homebrew 安装的 python（如 /opt/homebrew/bin/python3）虽可安全使用，但仍建议统一交由 pyenv 管理，确保版本切换干净、可重现。

• 安装 pyenv：brew install pyenv，并把 pyenv init 的 shell 配置写入 ~/.zshrc
• 安装指定版本：pyenv install 3.9.18 3.11.9 3.12.3
• 设全局默认版本：pyenv global 3.11.9；项目级局部版本：cd myproject && pyenv local 3.9.18
• 每次执行 python 命令时，pyenv 自动调用对应版本解释器，which python 显示的是 pyenv shims 路径，不是硬链接

每个 Python 版本配独立虚拟环境，不共用 site-packages

即使同一 Python 版本，不同项目也应使用独立虚拟环境（venv 或 virtualenv），否则 pip install 会污染全局 site-packages，导致依赖冲突或升级破坏其他项目。

• 创建环境：python -m venv .venv（用当前 pyenv 激活的 Python 版本）
• 激活环境：source .venv/bin/activate，此时 which pip 指向 .venv/bin/pip，pip list 只显示该环境下的包
• 推荐配合 direnv：在项目根目录放 .envrc，内容为 source .venv/bin/activate，进入目录自动激活，离开自动退出
• 不要用 pip install --user，它把包装进 ~/Library/Python/x.y/lib/python/site-packages/，仍属“用户级全局”，无法按项目隔离

用 pip-tools 或 poetry 锁定依赖，避免手动 pip install 失控

仅靠 venv 隔离还不够——如果多人协作或跨机器部署，pip install -r requirements.txt 仍可能因镜像源、wheel 编译差异或间接依赖版本浮动导致环境不一致。

立即学习“Python免费学习笔记（深入）”；

• pip-tools 流程：写 requirements.in（只列直接依赖），运行 pip-compile 生成带哈希和完整版本号的 requirements.txt，再 pip install -r requirements.txt
• poetry 更进一步：用 pyproject.toml 声明依赖，poetry install 自动创建虚拟环境、安装并锁定，poetry export -f requirements.txt 可导出兼容 pip 的文件
• 无论选哪种，都要把生成的锁文件（requirements.txt 或 poetry.lock）纳入 Git，这是可复现的关键

检查与清理：快速识别非隔离包安装

当你发现某个包“怎么删都还在”或“换个 Python 版本还能 import”，大概率是装到了错误位置。用这几条命令快速定位：

• python -c "import site; print(site.getsitepackages())" —— 查看当前解释器的 site-packages 路径
• python -c "import sys; print(sys.path)" —— 查看所有模块搜索路径，留意是否有 ~/Library/Python/ 或 /usr/local/lib/ 这类共享路径
• pip show package_name —— 看具体包装在哪，结合上面路径判断是否越界
• 误装到用户 site-packages？用 pip uninstall -y package_name + rm -rf ~/Library/Python/x.y/lib/python/site-packages/package* 彻底清理