跳到主要内容

安装 Python 环境

写 Python 代码的第一步，是拥有一套可用的 Python 运行环境。本章将带你完成以下几件事：

  • 在 Linux、Windows、macOS 三大平台上安装 Python 3.12+
  • 验证安装是否成功
  • 使用 pyenv 管理多个 Python 版本
  • 体验新一代包管理器 uv

:::tip 选哪个版本？ 本教程要求 Python 3.12 或更高版本。如果你愿意尝鲜，3.13 / 3.14 都可以使用；但若用于生产环境，建议优先选择已经稳定一段时间的版本（如 3.12、3.13）。 :::

在各平台上安装 Python​

Linux（Ubuntu / Debian）​

Ubuntu 24.04 及以上版本的官方源里通常已经包含较新的 Python。可以先检查一下：

# 查看仓库里可用的 Python 3 版本
apt list --installed 2>/dev/null | grep python3

# 查看当前版本
python3 --version

如果版本低于 3.12，可以添加 deadsnakes PPA 安装更新版本：

# 更新包索引并安装基础工具
sudo apt update
sudo apt install -y software-properties-common

# 添加 deadsnakes PPA（社区维护的 Python 源）
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt update

# 安装 Python 3.12 及 venv 模块
sudo apt install -y python3.12 python3.12-venv python3.12-dev

# 验证
python3.12 --version

:::warning 不要动系统的 python3 Linux 发行版很多系统工具（如 apt、gnome-terminal）依赖 python3。请勿将其替换为更高版本，否则可能导致系统异常。建议通过 python3.12 这样的带版本号命令调用，或用 pyenv 管理。 :::

CentOS / RHEL / Fedora​

# Fedora（较新版本自带 Python 3.12+）
sudo dnf install -y python3 python3-pip

# CentOS Stream 9 / RHEL 9（必要时启用 EPEL 与 dnf 模块）
sudo dnf install -y epel-release
sudo dnf module reset -y python3
sudo dnf module enable -y python3.12
sudo dnf install -y python3 python3-pip

Windows​

方式一：官网安装包​

  1. 访问 Python 官网下载页，选择 Python 3.12+ 的可执行安装包。
  2. 双击运行安装程序，务必勾选 "Add python.exe to PATH"。
  3. 选择 Install Now，等待安装完成。

:::warning 务必勾选加入 PATH 安装界面最下方有一个 "Add python.exe to PATH" 复选框，默认未勾选。如果漏勾，安装后命令行将无法直接使用 python 命令。万一漏勾了，可以重新运行安装程序选择 Modify，或手动把安装目录加入系统环境变量。 :::

方式二：winget（Windows 包管理器）​

# 安装最新稳定版 Python
winget install Python.Python.3.12

# 验证
python --version

方式三：Microsoft Store​

在 Microsoft Store 搜索 "Python"，选择 3.12 版本安装。这种方式的好处是自动处理 PATH，但路径较长，部分场景下不建议使用。

macOS​

方式一：Homebrew（推荐）​

# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python 3.12
brew install python@3.12

# 验证
python3.12 --version

方式二：官网安装包​

从 Python 官网 macOS 页面 下载 .pkg 安装包，双击按提示安装即可。安装后会自动放在 /Library/Frameworks/Python.framework，并创建 /usr/local/bin/python3（Intel）或 /opt/homebrew/bin/python3（Apple Silicon）的链接。

验证安装​

无论使用哪种平台，安装完成后都应通过下面的命令确认版本和包管理工具可用：

# 查看 Python 版本
python3 --version
# 期望输出类似：Python 3.12.x 或更高

# 查看 pip 版本（Python 的包管理工具）
python3 -m pip --version

# 进入交互式解释器
python3

:::tip python 与 python3 的区别

  • 在 Linux/macOS 上，python 通常不指向 Python 3，需要使用 python3。
  • 在 Windows 上，安装时勾选 PATH 后，python 即为 Python 3。
  • 本教程为统一，命令示例统一使用 python3；Windows 用户可直接使用 python。 :::

包管理工具：pip​

pip 是 Python 官方的包管理器，用于从 PyPI 安装第三方库。

# 安装一个包
python3 -m pip install requests

# 查看已安装的包
python3 -m pip list

# 升级一个包
python3 -m pip install --upgrade requests

# 卸载一个包
python3 -m pip uninstall requests

:::warning 不要直接在系统环境安装包 直接使用 pip install 往全局环境装包，会污染系统 Python，也可能触发 externally-managed-environment 错误（PEP 668）。推荐始终使用虚拟环境，详见下文 uv 一节。 :::

虚拟环境：venv​

虚拟环境能为每个项目隔离依赖，避免不同项目之间的库版本冲突。Python 自带 venv 模块：

# 在项目目录下创建虚拟环境（名为 .venv）
python3 -m venv .venv

# 激活虚拟环境
# Linux / macOS
source .venv/bin/activate
# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# 激活后，命令行前会出现 (.venv) 标记，此时 pip 安装的包只作用于该环境
pip install requests

# 退出虚拟环境
deactivate

使用 pyenv 管理多个版本​

当需要在不同项目之间切换 Python 版本时，pyenv 是最常用的工具。它通过在用户目录下编译多个 Python 解释器来实现版本切换，不会影响系统的 Python。

安装 pyenv​

# Linux / macOS（推荐一键安装脚本）
curl https://pyenv.run | bash

安装完成后，按提示把以下几行加入你的 shell 配置（~/.bashrc 或 ~/.zshrc）：

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
# 让 pyenv 在进入目录时自动切换版本
eval "$(pyenv init -)"

然后重启终端使其生效。

:::note Windows 用户 pyenv 原版只支持类 Unix 系统。Windows 上可使用 pyenv-win，安装与命令大同小异。 :::

常用命令​

# 查看所有可安装的版本
pyenv install --list | grep 3.12

# 安装某个版本（编译需要几分钟）
pyenv install 3.12.7

# 查看已安装版本
pyenv versions

# 设置全局默认版本
pyenv global 3.12.7

# 为当前目录设置版本（会写入 .python-version 文件）
pyenv local 3.12.7

:::tip 编译依赖 pyenv install 会从源码编译 Python，需要先安装编译依赖。Ubuntu 上执行：

sudo apt install -y build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev curl git \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

:::

使用 uv 管理项目与依赖​

uv 是由 Astral 团队用 Rust 编写的新一代 Python 包与项目管理器。它的速度比 pip 快 10 到 100 倍，并且集成了虚拟环境、版本管理、项目脚本运行等功能，是现代 Python 开发的首选工具。

安装 uv​

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 通过 pip 安装（适用于所有平台）
python3 -m pip install uv

# 验证
uv --version

uv 核心能力速览​

# 1. 创建项目（自动生成 pyproject.toml）
uv init my-project
cd my-project

# 2. 添加依赖（自动创建并管理 .venv）
uv add requests
uv add --dev pytest

# 3. 同步依赖（按 pyproject.toml 重建环境）
uv sync

# 4. 在项目环境里运行脚本或命令
uv run python main.py
uv run pytest

# 5. 安装指定版本的 Python（uv 自带构建好的发行版，无需编译）
uv python install 3.12 3.13

# 6. 把项目构建成可分发的包
uv build

:::info uv 与 pyenv 的关系 uv 内置了"安装指定版本 Python"的能力，并且不需要编译源码——它直接下载官方预构建的二进制。对于大多数用户来说，一个 uv 就能同时替代 pyenv + venv + pip + pip-tools。本教程后续示例也会大量使用 uv。 :::

实战：用 uv 创建第一个项目​

# 创建项目骨架
uv init hello-uv
cd hello-uv

# 查看自动生成的文件
ls -la
# 预期看到：pyproject.toml、main.py、README.md、.python-version 等

# 运行入口脚本
uv run main.py

打开 main.py，你会看到 uv 已经为你写好了入口：

def main() -> None:
    print("Hello from hello-uv!")

if __name__ == "__main__":
    main()

修改一下，加点颜色：

def main() -> None:
    print("Hello from hello-uv! 🚀")

if __name__ == "__main__":
    main()

再次运行：

uv run main.py
# 输出：Hello from hello-uv! 🚀

推荐的工具组合​

针对不同读者，我们推荐两套配置：

人群推荐组合说明
初学者官方安装包 + venv + pip简单直接，不引入额外概念
进阶 / 工程师uv 一站式速度快、跨平台一致、依赖锁定

:::tip 接下来 环境装好后，前往 第一个 Python 程序 编写并运行你的第一段代码。 :::

小结​

  • 三大平台都可通过官方安装包、系统包管理器或 winget/Homebrew 安装 Python 3.12+。
  • 安装后用 python3 --version 与 python3 -m pip --version 验证可用性。
  • 不要直接在系统环境安装第三方包，应使用 venv 虚拟环境隔离依赖。
  • pyenv 适合需要管理多个 Python 版本的开发者。
  • uv 是现代 Python 项目的首选工具，集成了版本管理、虚拟环境、依赖锁定的能力。