Python 编程教程 / 02 - 安装与环境配置

第 02 章：安装与环境配置

搭建 Python 开发环境，掌握版本管理和项目结构。

2.1 Python 安装

2.1.1 各平台安装方式

Linux（Ubuntu/Debian）

# Ubuntu 通常预装 Python 3，检查版本
$ python3 --version

# 安装 Python 3.12
$ sudo apt update
$ sudo apt install python3.12 python3.12-venv python3.12-dev

# 安装 pip
$ sudo apt install python3-pip

macOS

# 使用 Homebrew（推荐）
$ brew install python@3.12

# macOS 自带的 Python 2 已移除，注意区分
$ python3 --version

Windows

访问 https://www.python.org/downloads/
下载安装包，勾选 “Add Python to PATH”
验证安装：

> python --version
> pip --version

2.1.2 安装验证

# 检查 Python 和 pip 版本
$ python3 --version
Python 3.12.4

$ pip3 --version
pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.12)

# 检查 Python 路径
$ which python3
/usr/bin/python3

2.2 使用 pyenv 管理多版本

2.2.1 安装 pyenv

# macOS
$ brew install pyenv

# Linux（使用官方安装脚本）
$ curl https://pyenv.run | bash

配置 shell 环境（以 bash 为例，zsh 使用 .zshrc）：

# ~/.bashrc 或 ~/.zshrc
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

2.2.2 常用命令

命令	说明
`pyenv install --list`	查看可安装版本
`pyenv install 3.12.4`	安装指定版本
`pyenv versions`	查看已安装版本
`pyenv global 3.12.4`	设置全局默认版本
`pyenv local 3.11.9`	为当前目录设置版本
`pyenv shell 3.10.14`	为当前 shell 设置版本

# 安装 Python 3.12
$ pyenv install 3.12.4

# 设置全局版本
$ pyenv global 3.12.4

# 验证
$ python --version
Python 3.12.4

2.3 pip 包管理

2.3.1 基本用法

# 安装包
$ pip install requests

# 安装指定版本
$ pip install requests==2.31.0

# 升级包
$ pip install --upgrade requests

# 卸载包
$ pip uninstall requests

# 查看已安装的包
$ pip list

# 查看包信息
$ pip show requests

# 导出依赖
$ pip freeze > requirements.txt

# 从文件安装依赖
$ pip install -r requirements.txt

2.3.2 配置国内镜像源

临时使用：

$ pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

永久配置（推荐）：

# Linux/macOS: ~/.pip/pip.conf
# Windows: %APPDATA%\pip\pip.ini

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

2.3.3 常用镜像源

名称	地址
清华大学	https://pypi.tuna.tsinghua.edu.cn/simple
阿里云	https://mirrors.aliyun.com/pypi/simple
中科大	https://pypi.mirrors.ustc.edu.cn/simple
豆瓣	https://pypi.douban.com/simple

2.4 虚拟环境

2.4.1 为什么需要虚拟环境？

不同项目可能依赖不同版本的同一包。虚拟环境隔离项目依赖，避免冲突。

全局 Python
├── requests==2.28.0  ← 项目 A 需要
└── requests==2.31.0  ← 项目 B 需要  → 冲突！

使用虚拟环境：
项目 A → venv A → requests==2.28.0
项目 B → venv B → requests==2.31.0

2.4.2 venv（标准库）

# 创建虚拟环境
$ python3 -m venv .venv

# 激活（Linux/macOS）
$ source .venv/bin/activate

# 激活（Windows）
> .venv\Scripts\activate

# 确认使用的是虚拟环境中的 Python
(.venv) $ which python
/home/user/project/.venv/bin/python

# 退出虚拟环境
(.venv) $ deactivate

2.4.3 virtualenv

# 安装
$ pip install virtualenv

# 创建（比 venv 更快，支持更多特性）
$ virtualenv .venv

# 指定 Python 版本
$ virtualenv .venv --python=python3.12

2.4.4 Poetry（现代方案）

# 安装 Poetry
$ curl -sSL https://install.python-poetry.org | python3 -

# 创建新项目
$ poetry new myproject

# 在已有项目中初始化
$ poetry init

# 安装依赖
$ poetry add requests
$ poetry add --group dev pytest

# 运行命令
$ poetry run python main.py
$ poetry run pytest

# 激活虚拟环境
$ poetry shell

2.4.5 uv（极速方案）

# 安装 uv（比 pip 快 10–100 倍）
$ curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境
$ uv venv

# 安装包
$ uv pip install requests

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

2.4.6 方案对比

工具	速度	锁文件	项目管理	推荐场景
venv	中	❌	❌	简单项目
virtualenv	中	❌	❌	需要更多选项
Poetry	中	✅	✅	库开发
pdm	中	✅	✅	遵循 PEP 标准
uv	极快	✅	✅	全场景推荐

2.5 IDE 配置

2.5.1 VS Code（推荐）

安装 VS Code：https://code.visualstudio.com/
安装 Python 扩展：ms-python.python
配置解释器：Ctrl+Shift+P → Python: Select Interpreter → 选择虚拟环境

推荐扩展：

扩展	说明
Python	基础 Python 支持
Pylance	类型检查、自动补全
Ruff	代码格式化和 lint
Python Debugger	调试支持
Jupyter	Notebook 支持

settings.json 推荐配置：

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "[python]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports.ruff": "explicit"
        }
    },
    "python.analysis.typeCheckingMode": "basic"
}

2.5.2 PyCharm

Community 版：免费，适合纯 Python 开发
Professional 版：付费，支持 Web 框架、数据库工具
自带虚拟环境管理、调试器、数据库工具

2.5.3 其他选择

IDE/编辑器	特点
Neovim + LSP	高效键盘操作
Jupyter Lab	交互式数据分析
Cursor / Windsurf	AI 辅助编码

2.6 项目结构

2.6.1 标准项目布局

myproject/
├── .venv/                  # 虚拟环境（不纳入版本控制）
├── src/
│   └── myproject/
│       ├── __init__.py     # 包初始化
│       ├── main.py         # 程序入口
│       ├── models.py       # 数据模型
│       └── utils.py        # 工具函数
├── tests/
│   ├── __init__.py
│   ├── test_main.py
│   └── test_models.py
├── docs/                   # 文档
├── pyproject.toml          # 项目配置（PEP 621）
├── README.md               # 项目说明
├── .gitignore              # Git 忽略规则
├── .env                    # 环境变量（不纳入版本控制）
└── Makefile                # 常用命令

2.6.2 .gitignore 模板

# 虚拟环境
.venv/
venv/

# Python 缓存
__pycache__/
*.py[cod]
*.pyo
*.egg-info/
dist/
build/

# IDE
.vscode/
.idea/

# 环境变量
.env

# 系统文件
.DS_Store
Thumbs.db

2.6.3 pyproject.toml 基本模板

[project]
name = "myproject"
version = "0.1.0"
description = "My Python project"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
    "mypy>=1.10",
]

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B"]

[tool.mypy]
python_version = "3.11"
strict = true

2.6.4 Makefile

.PHONY: install test lint format run

install:
	pip install -e ".[dev]"

test:
	pytest tests/ -v

lint:
	ruff check src/ tests/

format:
	ruff format src/ tests/

run:
	python -m myproject.main

2.7 注意事项

🔴 注意：

不要使用系统自带的 Python 作为开发环境，使用 pyenv 或虚拟环境
永远不要用 sudo pip install，这会污染系统 Python
requirements.txt 要锁定版本号，避免不同环境行为不一致
不要将 .venv/ 目录提交到 Git

💡 提示：

使用 pyenv 管理多个 Python 版本
每个项目使用独立的虚拟环境
使用 uv 替代 pip 可以显著加速依赖安装
VS Code + Ruff + Pylance 是轻量高效的开发组合

📌 业务场景：团队协作时，统一项目结构和依赖管理至关重要：

使用 pyproject.toml 声明所有依赖
使用 poetry.lock 或 uv.lock 锁定版本
新成员只需 poetry install 即可获得一致的开发环境
CI/CD 中使用相同配置构建和测试