跳到主要内容

Python 环境配置

本章介绍如何安装 Python 解释器、配置开发环境，以及使用现代工具管理 Python 版本和项目依赖。

Python 解释器简介​

Python 解释器是执行 Python 代码的程序。它会读取你写的 Python 代码，并将其转换为计算机可以执行的指令。

Python 有多个实现版本：

  • CPython：官方实现，最广泛使用
  • PyPy：即时编译实现，执行速度快
  • Jython：运行在 Java 虚拟机上
  • IronPython：运行在 .NET 平台上

本教程以 CPython 为标准。

基础安装​

在 Windows 上安装 Python​

方法一：从官网下载安装​

  1. 访问 Python 官网下载页面
  2. 点击 "Download Python" 按钮下载最新版本
  3. 运行下载的安装程序
  4. 重要：勾选 "Add Python to PATH" 选项
  5. 点击 "Install Now" 进行安装

方法二：通过 Microsoft Store 安装​

  1. 打开 Microsoft Store
  2. 搜索 "Python"
  3. 选择 Python 3.x 版本
  4. 点击 "获取" 进行安装

验证安装​

python --version
# 输出: Python 3.13.2

# 查看安装路径
where python

在 macOS 上安装 Python​

方法一：从官网下载​

  1. 访问 Python 官网下载页面
  2. 下载最新的 macOS 安装包
  3. 运行安装包，按提示完成安装

方法二：使用 Homebrew（推荐）​

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

# 安装 Python
brew install python3

验证安装​

python3 --version

在 Linux 上安装 Python​

大多数 Linux 发行版已预装 Python。

# 检查版本
python3 --version

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip python3-venv

# CentOS/RHEL
sudo yum install python3 python3-pip

# Fedora
sudo dnf install python3 python3-pip

多版本管理：pyenv​

当需要在同一台机器上使用多个 Python 版本时，推荐使用 pyenv。它允许你在不同项目中使用不同的 Python 版本，而不会产生冲突。

pyenv 工作原理​

pyenv 通过在 PATH 中插入 shim（垫片）目录来拦截 Python 命令，然后根据配置决定使用哪个 Python 版本。版本选择顺序如下：

  1. PYENV_VERSION 环境变量（pyenv shell 设置）
  2. 当前目录的 .python-version 文件（pyenv local 设置）
  3. 全局配置文件（pyenv global 设置）
  4. 系统 Python

安装 pyenv​

macOS/Linux​

# 使用安装脚本
curl -fsSL https://pyenv.run | bash

# 或使用 Homebrew（macOS）
brew install pyenv

安装后，需要配置 shell：

# 对于 Bash，添加到 ~/.bashrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# 对于 Zsh，添加到 ~/.zshrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# 重新加载配置
source ~/.bashrc  # 或 source ~/.zshrc

Windows​

在 Windows 上使用 pyenv-win：

# 使用 pip 安装
pip install pyenv-win --target %USERPROFILE%\.pyenv

# 或使用 Chocolatey
choco install pyenv-win

配置环境变量：

  1. 添加 %USERPROFILE%\.pyenv\pyenv-win\bin 到 PATH
  2. 添加 %USERPROFILE%\.pyenv\pyenv-win\shims 到 PATH

pyenv 常用命令​

# 查看可安装的 Python 版本
pyenv install --list

# 安装特定版本
pyenv install 3.12.0
pyenv install 3.11.5
pyenv install 3.10.13

# 查看已安装的版本
pyenv versions

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

# 设置当前目录版本（项目级别）
pyenv local 3.11.5

# 设置当前 shell 会话版本
pyenv shell 3.10.13

# 查看当前使用的版本
pyenv version

# 查看版本路径
pyenv which python

# 卸载某个版本
pyenv uninstall 3.10.13

# 更新 pyenv
pyenv update  # 需要安装 pyenv-update 插件

版本选择示例​

# 场景：项目 A 需要 Python 3.11，项目 B 需要 Python 3.12

# 全局使用 3.12
pyenv global 3.12.0

# 进入项目 A 目录
cd ~/projects/project-a
pyenv local 3.11.5

# 验证
python --version  # 输出: Python 3.11.5

# 进入项目 B 目录
cd ~/projects/project-b
python --version  # 输出: Python 3.12.0

依赖管理：Poetry​

Poetry 是现代 Python 项目依赖管理工具，提供依赖解析、虚拟环境管理、打包发布等功能。

为什么选择 Poetry？​

特性pip + venvPoetry
依赖解析手动管理自动解析依赖冲突
锁定版本requirements.txtpoetry.lock（自动生成）
虚拟环境需手动创建自动管理
项目结构自由定义标准化结构
打包发布需要 setup.py内置支持

安装 Poetry​

# 官方推荐方式
curl -sSL https://install.python-poetry.org | python3 -

# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

# 使用 pip
pip install poetry

# 验证安装
poetry --version

创建新项目​

# 创建新项目
poetry new my-project

# 项目结构
# my-project/
# ├── pyproject.toml
# ├── README.md
# ├── src/
# │   └── my_project/
# │       └── __init__.py
# └── tests/
#     └── __init__.py

# 在现有目录初始化
cd existing-project
poetry init

pyproject.toml 配置文件​

[project]
name = "my-project"
version = "0.1.0"
description = "A sample project"
authors = [
    {name = "Your Name", email = "you@example.com"}
]
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "requests>=2.28.0",
    "pandas>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
]

[build-system]
requires = ["poetry-core>=2.0.0"]
build-backend = "poetry.core.masonry.api"

依赖管理​

# 添加依赖
poetry add requests
poetry add "pandas>=2.0.0,<3.0.0"

# 添加开发依赖
poetry add --group dev pytest
poetry add --group dev black ruff

# 安装所有依赖
poetry install

# 只安装主依赖（不含开发依赖）
poetry install --only main

# 更新依赖
poetry update              # 更新所有依赖
poetry update requests     # 更新特定依赖

# 移除依赖
poetry remove requests
poetry remove --group dev pytest

# 查看依赖树
poetry show --tree

# 查看过时的依赖
poetry show --outdated

虚拟环境管理​

# Poetry 自动创建虚拟环境

# 运行命令（在虚拟环境中）
poetry run python main.py
poetry run pytest

# 激活虚拟环境
poetry shell

# 退出虚拟环境
exit

# 查看虚拟环境信息
poetry env info

# 查看所有虚拟环境
poetry env list

# 删除虚拟环境
poetry env remove python3.11

# 在项目目录内创建虚拟环境
poetry config virtualenvs.in-project true

版本约束语法​

[project]
dependencies = [
    "requests",           # 任意版本
    "flask>=2.0.0",       # 大于等于 2.0.0
    "django>=3.0,<4.0",   # 3.x 版本
    "numpy~=1.24.0",      # 1.24.x（相当于 >=1.24.0,<1.25.0）
    "pandas==2.0.0",      # 精确版本
]

构建和发布​

# 构建包
poetry build
# 生成 dist/
# ├── my_project-0.1.0-py3-none-any.whl
# └── my-project-0.1.0.tar.gz

# 发布到 PyPI
poetry publish

# 配置 PyPI 凭证
poetry config pypi-token.pypi <token>

其他包管理工具​

pip + venv（传统方式）​

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# 安装依赖
pip install requests
pip install -r requirements.txt

# 导出依赖
pip freeze > requirements.txt

# 退出虚拟环境
deactivate

uv（新一代快速工具）​

uv 是用 Rust 编写的超快速 Python 包管理器，比 pip 快 10-100 倍。

# 安装 uv
pip install uv

# 创建虚拟环境
uv venv

# 安装包
uv pip install requests

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 同步环境
uv pip sync requirements.txt

Pipenv​

Pipenv 结合了 pip 和 virtualenv，使用 Pipfile 管理依赖。

# 安装
pip install pipenv

# 创建虚拟环境并安装依赖
pipenv install requests

# 安装开发依赖
pipenv install --dev pytest

# 激活虚拟环境
pipenv shell

# 运行命令
pipenv run python main.py

工具选择建议​

推荐组合​

场景推荐方案
学习/个人项目系统 Python + pip + venv
专业开发pyenv + Poetry
快速原型uv
团队协作Poetry（统一环境）
库开发Poetry

IDE 配置​

Visual Studio Code（推荐）​

  1. 安装 VS Code：官网下载
  2. 安装 Python 扩展：
    • 打开扩展面板（Ctrl+Shift+X）
    • 搜索 "Python"
    • 安装 Microsoft 官方扩展

配置 Python 解释器：

  1. 按 Ctrl+Shift+P
  2. 输入 "Python: Select Interpreter"
  3. 选择项目使用的 Python 版本

推荐扩展：

  • Python（Microsoft）
  • Pylance（类型检查）
  • Python Debugger
  • Ruff（代码格式化和 linting）

PyCharm​

  1. 下载 PyCharm
  2. 社区版免费，专业版付费
  3. 配置解释器：Settings → Project → Python Interpreter

第一个 Python 程序​

安装好环境后，让我们编写第一个 Python 程序：

# hello.py
print("Hello, World!")

# 使用 f-string 格式化
name = "Python"
version = 3.13
print(f"欢迎使用 {name} {version}！")

运行方式：

# 直接运行
python hello.py

# 使用 Poetry
poetry run python hello.py

# 交互模式
python
>>> print("Hello, World!")
Hello, World!
>>> exit()

常见问题排查​

1. python 命令不存在​

# Windows: 确认 PATH 配置
where python

# macOS/Linux: 使用 python3
python3 --version

# 或创建别名（macOS/Linux）
echo "alias python=python3" >> ~/.bashrc

2. pip 安装包时权限错误​

# 错误: Permission denied

# 解决方案1: 使用 --user（不推荐）
pip install package --user

# 解决方案2: 使用虚拟环境（推荐）
python -m venv .venv
source .venv/bin/activate
pip install package

3. 虚拟环境激活失败（Windows）​

# 错误: 无法加载文件，因为在此系统上禁止运行脚本

# 解决方案: 修改执行策略
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

4. Poetry 安装依赖失败​

# 清除缓存
poetry cache clear pypi --all

# 重新安装
poetry install --no-cache

5. pyenv 安装 Python 版本失败​

# macOS: 安装编译依赖
brew install openssl readline sqlite3 xz zlib

# Ubuntu/Debian
sudo apt install build-essential libssl-dev zlib1g-dev \
    libbz2-dev libreadline-dev libsqlite3-dev curl \
    libncursesw5-dev xz-utils tk-dev libxml2-dev \
    libxmlsec1-dev libffi-dev liblzma-dev

# 然后重试安装
pyenv install 3.12.0

6. 多个 Python 版本冲突​

# 查看当前使用的 Python
which python
pyenv which python

# 查看所有版本
pyenv versions

# 确保 pyenv shim 在 PATH 最前面
echo $PATH

小结​

本章我们学习了：

  1. Python 解释器的基本概念和安装方法
  2. 使用 pyenv 管理多个 Python 版本
  3. 使用 Poetry 进行依赖管理
  4. 其他工具：pip + venv、uv、Pipenv
  5. IDE 配置和常见问题解决

推荐的学习路径：

  1. 初学者：使用系统 Python + pip + venv
  2. 进阶开发：使用 pyenv + Poetry
  3. 追求性能：考虑使用 uv

练习​

  1. 在你的电脑上安装 Python 解释器
  2. 安装 VS Code 并配置 Python 扩展
  3. 使用 pyenv 安装两个不同的 Python 版本并切换
  4. 使用 Poetry 创建一个新项目，添加 requests 依赖
  5. 编写并运行 "Hello, World!" 程序

延伸阅读​