Python 安装指南
中心论点
Python 环境管理的核心矛盾不是「装不装」，而是「装完之后怎么不把系统搞乱」。安装 Python 只需 3 分钟，但一个规范的环境配置能让你在未来 3 年里避免 90% 的依赖冲突和版本混乱。本文给出 macOS 和 Windows 两条黄金路径——每一步都有明确的「为什么」。
阅读指南
| 读者画像 | 建议阅读路径 |
|---|---|
| 电脑完全没有 Python，想尽快跑起来 | 直接看「macOS 黄金路径」或「Windows 黄金路径」→ 验证安装 → 虚拟环境速成 |
| 已有 Python 但版本混乱 / 想规范化 | 先看「诊断你的现状」→ 多版本管理 → 环境隔离规范 |
| 需要同时维护多个项目 / 多 Python 版本 | 全文通读，重点看「多版本管理」和「工具链选型」 |
1. 先搞清楚：你的电脑现在什么状态？
在安装之前，先诊断。打开终端（macOS: Terminal / Windows: PowerShell），依次执行：
Bash
# 检查是否有 python3（macOS 常见）
python3 --version
# 检查是否有 python（Windows 常见）
python --version
# 检查 pip
pip3 --version
pip --version
# 检查 PATH 中有几个 python
which -a python3 # macOS/Linux
where python # WindowsmacOS 陷阱
macOS 自带的 /usr/bin/python3 是 Apple 为 Xcode 工具链准备的阉割版——没有 pip、没有完整标准库、版本老旧。永远不要用它做开发。你需要安装一个独立的 Python。
Windows 陷阱
Windows 不预装 Python。但如果你在终端输入 python，系统可能会弹出 Microsoft Store 页面——这不是报错，是 Windows 在引导你安装。
2. macOS 黄金路径
Mermaid
正在渲染 Mermaid 图表…
2.1 安装 Homebrew（如果没有）
Homebrew 是 macOS 的包管理器，Python 官方文档将其列为 Alternative Distributions 首选。
Bash
# 安装 Homebrew（一行命令）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Apple Silicon Mac 需要额外执行（安装脚本会提示）
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
# 验证
brew --version2.2 安装 Python
Bash
# 安装最新稳定版
brew install python@3.14
# 验证（注意：macOS 上命令是 python3，不是 python）
python3 --version # → Python 3.14.x
pip3 --version # → pip 25.x from ...
which python3 # → /opt/homebrew/bin/python3（Apple Silicon）
# → /usr/local/bin/python3（Intel Mac）为什么选 Homebrew 而不是官方 .pkg 安装器？
官方 .pkg 安装到 /Library/Frameworks/Python.framework，卸载需要手动删 3 个目录。Homebrew 安装的 Python 可以 brew uninstall python@3.14 一行卸载，且版本升级只需 brew upgrade python。对于开发者来说，可管理性 > 一切。
2.3 （可选）官方 .pkg 安装器方式
如果你不想装 Homebrew，也可以用官方安装器：
- 访问 python.org/downloads/macos
- 下载最新 macOS installer (universal2)——同时支持 Apple Silicon 和 Intel
- 双击
.pkg文件，按向导走完 - 关键步骤： 安装完成后，双击
/Applications/Python 3.14/Install Certificates.command——这会安装 SSL 根证书，否则 pip 和 requests 等网络库会报 SSL 错误 - 验证：
python3 --version
默认安装位置：
- Framework:
/Library/Frameworks/Python.framework - 应用目录:
/Applications/Python 3.14/ - Symlinks:
/usr/local/bin/python3、/usr/local/bin/pip3
3. Windows 黄金路径
Mermaid
正在渲染 Mermaid 图表…
3.1 方式 A：Python Install Manager（推荐，Python 3.14+ 新方式）
Python 3.14 引入了全新的 Python Install Manager（py 命令），这是官方推荐的 Windows 安装管理方式：
Powershell
# 方式 1：从 Microsoft Store 安装（最简单）
# 在 Microsoft Store 搜索 "Python" → 点击 Install
# 方式 2：从 python.org 下载 MSIX 安装包
# 访问 python.org/downloads → 下载 Windows installer
# 安装后，打开终端输入：
python # 如果没有安装任何运行时，会自动安装最新稳定版
# 管理多版本
py list # 列出已安装版本
py install 3.14 # 安装指定版本
py -V:3.14 ... # 使用指定版本运行
py list --online # 查看可安装的版本3.2 方式 B：传统 .exe 安装器
- 访问 python.org/downloads
- 下载 Windows installer (64-bit)
- 运行安装器
最关键的一步
安装界面底部有一个复选框 "Add python.exe to PATH"——必须勾选！ 不勾选意味着系统找不到 python 命令，你会在终端看到 'python' is not recognized。如果忘了勾选，需要手动添加环境变量或重新安装。
- 点击 "Install Now"（默认安装）或 "Customize installation" → 勾选 "Add Python to environment variables"
- 安装完成后重启终端（重要！已打开的终端不会读取新的 PATH）
Powershell
# 验证
python --version # → Python 3.14.x
pip --version # → pip 25.x
where python # → C:\Users\<你的用户名>\AppData\Local\Programs\Python\Python314\python.exe3.3 Windows 安装方式对比
| 方式 | 优点 | 缺点 | 推荐场景 |
|---|---|---|---|
| Install Manager (Store) | 自动更新、多版本共存、py 命令统一入口 | Python 3.14+ 才有，较新 | ✅ 新电脑首选 |
| 传统 .exe 安装器 | 久经考验、文档丰富 | 多版本管理需手动、PATH 容易搞乱 | 企业受限环境 |
| winget | winget install Python.Python.3.14 一行搞定 | 版本更新有延迟 | 喜欢命令行的用户 |
| Anaconda / Miniconda | 科学计算生态完整 | 体积大（3GB+）、PATH 冲突多 | 数据科学专用 |
4. 安装验证清单
安装完成后，运行以下命令确认环境正常：
Bash
# ① Python 版本
python3 --version # macOS
python --version # Windows
# ② pip 版本
pip3 --version # macOS
pip --version # Windows
# ③ 能否创建虚拟环境
python3 -m venv /tmp/test-venv # macOS
python -m venv %TEMP%\test-venv # Windows
# ④ 能否安装包
pip3 install --dry-run requests # macOS（dry-run 不实际安装）
pip install --dry-run requests # Windows
# ⑤ SSL 证书正常（macOS 官方安装器用户必测）
python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"全部通过？
恭喜，你的 Python 环境已就绪。接下来最重要的事情是：永远不要在系统 Python 里直接 pip install——请使用虚拟环境。
5. 虚拟环境：你必须掌握的第一个规范
5.1 为什么必须用虚拟环境？
不用虚拟环境的后果：
- 项目 A 需要
requests==2.28，项目 B 需要requests==2.31→ 依赖冲突 - 全局
pip install污染系统 Python → 其他工具莫名报错 - AI 工具（Codex、Cursor、Copilot）在本地执行脚本时混用全局包 → 不可复现
5.2 标准做法：venv（内置，零额外安装）
Bash
# macOS
cd ~/my-project
python3 -m venv .venv # 创建虚拟环境
source .venv/bin/activate # 激活
pip install requests # 在虚拟环境内安装
deactivate # 退出虚拟环境
# Windows (PowerShell)
cd ~\my-project
python -m venv .venv # 创建虚拟环境
.venv\Scripts\Activate # 激活
pip install requests # 在虚拟环境内安装
deactivate # 退出虚拟环境命名规范
虚拟环境目录统一命名 .venv（带点号），这是 Python 社区的事实标准。VS Code、PyCharm 等 IDE 会自动识别 .venv 目录并激活。务必将 .venv/ 加入 .gitignore。
5.3 虚拟环境原则
| 原则 | 说明 |
|---|---|
每个项目一个 .venv | 绝不跨项目共享虚拟环境 |
| 虚拟环境是一次性的 | 坏了就删掉重建，不要试图修复 |
| 依赖锁定 | pip freeze > requirements.txt 记录精确版本 |
不提交 .venv | 只提交 requirements.txt 或 pyproject.toml |
6. 多版本管理
当你需要同时维护多个 Python 版本时（例如一个项目用 3.12，另一个用 3.14），单靠 Homebrew 或官方安装器不够优雅。
6.1 macOS：pyenv
pyenv 是 macOS/Linux 下的 Python 版本管理事实标准。
Bash
# 安装 pyenv
brew install pyenv pyenv-virtualenv
# 配置 shell（zsh，macOS 默认）
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc
source ~/.zshrc
# 安装多个 Python 版本
pyenv install 3.12.8
pyenv install 3.14.3
# 设置全局默认
pyenv global 3.14.3
# 为特定项目设置版本（会创建 .python-version 文件）
cd ~/project-legacy
pyenv local 3.12.8
# 创建虚拟环境
pyenv virtualenv 3.14.3 my-project-env
pyenv activate my-project-env6.2 Windows：Python Install Manager (py)
Windows 的多版本管理由官方 py launcher 原生支持：
Powershell
# 安装多个版本
py install 3.12
py install 3.14
# 列出已安装版本
py list
# 使用指定版本
py -V:3.12 -m venv .venv # 用 3.12 创建虚拟环境
py -V:3.14 script.py # 用 3.14 运行脚本
# 设置默认版本
set PYTHON_MANAGER_DEFAULT=3.146.3 跨平台方案：uv（新一代，推荐关注）
uv 是 Astral 团队（Ruff 的作者）用 Rust 构建的全能 Python 工具，速度比 pip 快 10-100 倍，可以替代 pip + venv + pyenv + pip-tools：
Bash
# 安装 uv
# macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 用 uv 管理 Python 版本
uv python install 3.14
uv python install 3.12
uv python list
# 用 uv 创建虚拟环境
uv venv --python 3.14
# 用 uv 安装包（极快）
uv pip install requests numpy pandas
# 用 uv 初始化项目（生成 pyproject.toml）
uv init my-project
cd my-project
uv add requests
uv run python main.py7. 工具链选型：该用哪个？
| 工具 | 定位 | 版本管理 | 虚拟环境 | 包安装 | 速度 | 推荐度 |
|---|---|---|---|---|---|---|
| venv + pip | Python 内置 | ❌ | ✅ | ✅ | 慢 | ⭐⭐⭐ 入门首选 |
| pyenv | 版本管理 | ✅ | ✅（插件） | ❌ | — | ⭐⭐⭐⭐ macOS 标配 |
| uv | 全能替代 | ✅ | ✅ | ✅ | 极快 | ⭐⭐⭐⭐⭐ 未来方向 |
| Poetry | 项目管理 | ❌ | ✅ | ✅ | 中等 | ⭐⭐⭐ 库开发 |
| Conda | 科学计算 | ✅ | ✅ | ✅ | 慢 | ⭐⭐ 仅数据科学 |
我的推荐
- 新手 / 只用一个版本： 系统装好 Python + venv + pip，够用
- macOS 多版本开发者： Homebrew + pyenv + pyenv-virtualenv
- 想要最现代的体验： uv（一个工具搞定一切，速度碾压）
- Windows 用户： Python Install Manager + venv（官方原生方案最省心）
8. PATH 环境变量：理解了就不会再出错
大部分 Python 安装问题的根源都是 PATH 配置错误。
8.1 PATH 是什么？
当你在终端输入 python 时，系统会按 PATH 变量中列出的目录从左到右依次查找名为 python 的可执行文件，找到第一个就执行。
8.2 macOS PATH 排查
Bash
# 查看完整 PATH
echo $PATH | tr ':' '\n'
# 查看 python3 实际指向哪里
which python3
ls -la $(which python3) # 看是否是 symlink
# 常见正确路径
# Homebrew (Apple Silicon): /opt/homebrew/bin/python3
# Homebrew (Intel): /usr/local/bin/python3
# 官方安装器: /Library/Frameworks/Python.framework/Versions/3.14/bin/python3
# pyenv: ~/.pyenv/shims/python38.3 Windows PATH 排查
Powershell
# 查看 PATH
$env:PATH -split ';'
# 查看 python 位置
where python
# 常见正确路径
# 传统安装器: C:\Users\<User>\AppData\Local\Programs\Python\Python314\
# Store 安装: C:\Users\<User>\AppData\Local\Microsoft\WindowsApps\
# py launcher: 系统 PATH 中PATH 冲突排查口诀
which -a python3（macOS）或where python（Windows）——看有几个- 如果有多个，排在前面的赢
- 虚拟环境激活后，
.venv/bin会被插入 PATH 最前面——这就是虚拟环境的隔离原理
9. 故障模式与排查
| 症状 | 平台 | 根因 | 解决方案 |
|---|---|---|---|
python: command not found | macOS | macOS 没有 python 命令，只有 python3 | 使用 python3，或添加 alias: alias python=python3 |
'python' is not recognized | Windows | 安装时没勾选 Add to PATH | 重新运行安装器 → Modify → 勾选 Add to PATH；或手动添加环境变量 |
pip install 权限报错 | 两者 | 尝试写入系统 Python 的 site-packages | 永远不要 sudo pip install，使用虚拟环境或 pip install --user |
SSL: CERTIFICATE_VERIFY_FAILED | macOS | 官方安装器用户没运行 Install Certificates.command | 双击 /Applications/Python 3.14/Install Certificates.command |
| 装了包但 import 找不到 | 两者 | pip 和 python 指向不同安装 | 始终用 python3 -m pip install 而不是裸 pip |
| 虚拟环境激活后还是用系统 Python | Windows | PowerShell 执行策略限制 | Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser |
| AI 工具报 "没有 python" | 两者 | AI 工具找不到 PATH 中的 python | 安装 Python 后重启终端和 AI 工具；确认 python3（macOS）或 python（Windows）在 PATH 中 |
10. 给 AI 工具用户的特别说明
你遇到的 "本机没有 python" 正是这个场景：AI Coding Agent（如 Codex、Cursor Agent、Copilot）需要在本地执行 Python 脚本来完成任务。
10.1 AI 工具对 Python 环境的要求
- PATH 可达： AI 工具通常通过
python或python3命令调用 Python，不会去找非标准路径 - 常用包可用： 很多 AI 生成的脚本会
import json, os, sys, re（标准库）以及requests, yaml（第三方） - 虚拟环境兼容： 部分工具会在项目根目录寻找
.venv
10.2 最小化配置方案
Bash
# macOS：安装 Python + 常用包
brew install python@3.14
python3 -m pip install --user requests pyyaml
# Windows：安装 Python + 常用包
# 安装 Python Install Manager 或传统安装器（记得勾 PATH）
python -m pip install requests pyyaml
# 验证 AI 工具能找到 python
which python3 # macOS
where python # WindowsPro Tip
如果你的 AI 工具仍然找不到 Python，尝试在工具的设置中手动指定 Python 解释器路径。VS Code 用户可以 Cmd+Shift+P → "Python: Select Interpreter"。
11. 一页速查表
| 操作 | macOS | Windows |
|---|---|---|
| 安装 Python | brew install python@3.14 | Microsoft Store 或 python.org 下载 |
| 运行 Python | python3 | python 或 py |
| 查看版本 | python3 --version | python --version |
| 创建虚拟环境 | python3 -m venv .venv | python -m venv .venv |
| 激活虚拟环境 | source .venv/bin/activate | .venv\Scripts\Activate |
| 退出虚拟环境 | deactivate | deactivate |
| 安装包 | pip install <包名> | pip install <包名> |
| 锁定依赖 | pip freeze > requirements.txt | pip freeze > requirements.txt |
| 多版本管理 | pyenv install 3.x.x | py install 3.x |
| 查看 Python 位置 | which python3 | where python |
12. 已知局限
- Python Install Manager 仅限 Python 3.14+： 旧版 Windows 用户（或需要 3.12/3.13 的用户）仍需使用传统安装器 +
py.exelauncher - Homebrew Python 不含 IDLE 和 Tkinter： 如果需要 GUI 开发，用官方 .pkg 安装器或
brew install python-tk@3.14 - pyenv 在 Windows 上不可用： pyenv 是 Unix-only 工具，Windows 用户应使用
pylauncher 或 pyenv-win（社区维护，非官方） - uv 仍在快速迭代中： API 可能变化，生产环境建议锁定 uv 版本
- Apple Silicon 与 Intel 路径不同： Homebrew 在 Apple Silicon 安装到
/opt/homebrew/，Intel 安装到/usr/local/——复制网上教程时注意路径差异
接下来读什么
| 方向 | 资源 | 说明 |
|---|---|---|
| Python 官方文档 | Using Python on macOS / Using Python on Windows | 权威参考，本文的主要信息源 |
| uv 官方文档 | docs.astral.sh/uv | 新一代 Python 工具链，强烈推荐了解 |
| pyenv 教程 | Real Python: Managing Multiple Python Versions | 最佳 pyenv 入门教程 |
| Python Packaging Guide | packaging.python.org | 官方打包指南，进阶必读 |
| The Hitchhiker's Guide | docs.python-guide.org | 社区最佳实践大全 |