跳到主要内容

安装第三方模块

Python 标准库提供了许多常用功能，但数据库访问、Web 开发、数据分析等场景通常还需要第三方包。安装第三方包时，最稳妥的做法是：为每个项目创建虚拟环境，再使用该环境中的 Python 执行 pip。

本文使用 Python 3.10 及以上版本。读完后，你应该能够：

  • 区分“发行包名称”和“导入名称”；
  • 使用 venv 创建并启用项目专属环境；
  • 使用 python -m pip 安装、查看、升级和卸载包；
  • 通过依赖文件复现开发环境；
  • 排查“安装成功但无法导入”、权限错误和版本冲突等问题。

第三方模块从哪里来​

第三方模块不是 Python 自带的代码，通常由社区开发者发布到 Python Package Index（PyPI），再由 pip 下载并安装。

这里有三个容易混淆的概念：

概念含义示例
发行包安装工具识别的发布单位requests、beautifulsoup4
导入包/模块Python 代码中的导入名称requests、bs4
pip安装和管理 Python 发行包的工具python -m pip install requests

发行包名称与导入名称不一定相同。例如：

python -m pip install beautifulsoup4

安装后使用的却是：

from bs4 import BeautifulSoup

因此，安装命令和导入写法都应以项目的官方文档为准，不要根据名称猜测。

标准安装流程​

下面以新项目 weather-app 和第三方包 requests 为例。

1. 确认 Python 解释器​

先检查当前终端调用的是哪个 Python：

python --version
python -c "import sys; print(sys.executable)"

部分 Linux 或 macOS 环境只提供 python3 命令，此时把本文命令中的 python 换成 python3：

python3 --version

sys.executable 会输出解释器的实际路径，排查环境问题时比只看版本号更可靠。

2. 创建虚拟环境​

进入项目目录后创建名为 .venv 的虚拟环境：

mkdir weather-app
cd weather-app
python -m venv .venv

虚拟环境是一个独立的 Python 运行环境。安装到其中的包只服务于当前项目，不会污染系统 Python，也不会和其他项目要求的版本互相干扰。

.venv 是常见目录名，通常应加入 Git 忽略文件，而不是提交到仓库：

.gitignore
.venv/

项目应该提交依赖声明，让其他开发者重新安装，而不是复制整套虚拟环境。

3. 启用虚拟环境​

macOS、Linux 或 Git Bash：

source .venv/bin/activate

Windows PowerShell：

.venv\Scripts\Activate.ps1

Windows 命令提示符：

.venv\Scripts\activate.bat

启用后，终端提示符通常会出现 (.venv)。再次确认解释器路径：

python -c "import sys; print(sys.executable)"

输出路径应该指向项目中的 .venv。完成工作后可退出环境：

deactivate

“启用”本质上是临时调整当前终端的命令搜索路径。即使不启用，也可以直接运行虚拟环境中的解释器，例如 macOS/Linux 使用 .venv/bin/python，Windows 使用 .venv\Scripts\python.exe。

4. 使用 pip 安装包​

启用虚拟环境后执行：

python -m pip install requests

推荐写 python -m pip，而不是直接写 pip。前者明确表示“使用当前这个 Python 对应的 pip”，可以减少包被安装到另一个解释器中的情况。

安装时，pip 会解析 requests 声明的依赖，并把所需包一起安装。不要看到多个包被安装就立即认为出现了异常，它们可能是正常的间接依赖。

5. 验证安装结果​

查看包的信息：

python -m pip show requests

测试是否可以导入，并输出版本与安装位置：

python -c "import requests; print(requests.__version__); print(requests.__file__)"

也可以创建一个最小程序：

main.py
import requests

response = requests.get("https://example.com", timeout=10)
response.raise_for_status()
print(response.status_code)

运行程序：

python main.py

安装成功只说明包可以被当前环境使用。具体 API、异常处理和安全要求仍应阅读该包的官方文档。

指定安装版本​

不指定版本时，pip 通常会选择满足当前 Python 版本和平台条件的最新可用版本：

python -m pip install requests

也可以使用版本约束：

# 精确版本
python -m pip install "requests==2.32.5"

# 至少为 2.31.0
python -m pip install "requests>=2.31.0"

# 允许兼容范围，不安装 3.x
python -m pip install "requests>=2.31,<3"

# 兼容发布版本：至少 2.32，但低于 3.0
python -m pip install "requests~=2.32"

含有 <、> 等字符时应加引号，避免被命令行解释为输入输出重定向。

不同约束适合不同目的：

场景常见选择
临时试用不指定版本
应用项目需要稳定复现记录经过测试的精确版本
可复用库声明依赖设置合理范围，避免限制过死

安装前可以查看 PyPI 页面和项目发布说明，确认所选版本支持当前 Python 版本。不要为了安装一个包而随意降低整个环境的安全性或覆盖系统组件。

记录并复现依赖​

使用 requirements.txt​

小型项目常用 requirements.txt 记录需要安装的包：

requirements.txt
requests==2.32.5

根据文件安装：

python -m pip install -r requirements.txt

也可以把当前环境中所有已安装包及其精确版本导出：

python -m pip freeze > requirements.txt

pip freeze 会同时记录直接依赖和间接依赖，适合生成某个环境的完整快照，但它不会说明“项目主动使用了哪些包”。如果环境里装过无关工具，结果也会被写入文件。因此应在干净的项目虚拟环境中执行，并在提交前检查内容。

复现环境时，可以重新创建虚拟环境再安装：

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Windows 用户只需把启用命令换成前文对应的命令。

使用 pyproject.toml​

现代 Python 项目也常在 pyproject.toml 中声明项目元数据和直接依赖：

pyproject.toml
[project]
name = "weather-app"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
  "requests>=2.31,<3",
]

如果当前目录是一个配置完整、可安装的 Python 项目，可以执行：

python -m pip install .

开发项目时常使用可编辑安装：

python -m pip install -e .

可编辑安装让 Python 直接使用工作目录中的项目代码，修改源码后通常不必重复安装。pyproject.toml 是否能直接安装，还取决于项目是否正确配置了构建后端和包结构；不要只复制上面的依赖片段就假定项目已经可安装。

requirements.txt 更像某个环境的安装清单，pyproject.toml 更适合描述项目本身及其直接依赖。实际团队还可能使用锁文件和 Poetry、PDM、uv 等工具，应遵循所在项目已经采用的工具和约定，不要混用多个依赖管理流程。

常用管理命令​

查看已安装的包​

python -m pip list
python -m pip show requests

查看存在新版本的包：

python -m pip list --outdated

升级包​

python -m pip install --upgrade requests

升级可能带来不兼容修改。应用项目应先查看发布说明，在独立分支或测试环境中升级，并运行测试后再更新依赖记录。

卸载包​

python -m pip uninstall requests

pip uninstall 通常只卸载指定包，不会自动判断某个间接依赖是否已不再需要。不要盲目批量删除环境中的包；难以整理时，依据依赖文件重建虚拟环境通常更清晰。

检查依赖是否一致​

python -m pip check

如果已安装包所要求的版本不满足，pip check 会报告冲突。它只能检查已声明的依赖关系，不能代替项目测试。

安全安装第三方包​

安装包会在本机引入并运行他人发布的代码，因此应把安装依赖视为代码变更：

  • 从项目官方文档确认发行包名称，警惕与知名包拼写相近的恶意包；
  • 检查项目维护状态、源码地址、发布时间和安全公告；
  • 优先使用默认的 HTTPS PyPI 源或组织批准的镜像；
  • 不要随意使用来历不明的 --index-url、--trusted-host 或安装脚本；
  • 在虚拟环境中安装，不使用 sudo pip install ... 修改系统 Python；
  • 记录并审查依赖变更，定期升级存在安全问题的版本。

从本地目录、Git 仓库或 URL 安装虽然可行，但可复现性和供应链风险更难控制。只有在理解来源、版本固定方式和团队规范后才应使用。

常见问题​

安装成功，但仍然提示 ModuleNotFoundError​

最常见原因是“安装时使用的 Python”和“运行程序时使用的 Python”不是同一个。分别检查：

python -c "import sys; print(sys.executable)"
python -m pip --version

pip --version 输出中会包含安装位置和对应的 Python 版本。还应确认：

  1. 已在当前终端启用正确的虚拟环境；
  2. 编辑器选择的解释器指向项目中的 .venv；
  3. 发行包名称和导入名称是否不同；
  4. 当前目录中是否有同名 .py 文件遮蔽第三方模块。

不要通过修改 sys.path 或把包文件复制进项目来掩盖环境问题。

出现权限错误或 externally-managed-environment​

这通常表示正在尝试修改操作系统或包管理器维护的 Python。正确做法是创建并使用虚拟环境：

python -m venv .venv
source .venv/bin/activate
python -m pip install <package-name>

不要用 sudo，也不要轻易添加 --break-system-packages 绕过保护；这可能破坏操作系统工具依赖的 Python 环境。

提示找不到匹配的发行版本​

常见原因包括：

  • 包名或版本号写错；
  • 当前 Python 版本过新或过旧；
  • 操作系统、CPU 架构不受支持；
  • 指定的镜像尚未同步该版本；
  • 网络、代理或证书配置阻止了索引访问。

先阅读完整错误信息，再检查版本兼容表。可以使用以下命令确认环境信息：

python --version
python -m pip --version
python -c "import platform; print(platform.system(), platform.machine())"

依赖版本冲突​

当两个包要求同一依赖的不同版本时，pip 可能无法找到可行组合，或现有环境已经不一致。建议：

  1. 查看错误中各包声明的版本范围；
  2. 删除没有依据的过度精确限制；
  3. 尝试升级直接依赖到彼此兼容的版本；
  4. 在全新虚拟环境中重新安装依赖；
  5. 执行 python -m pip check 并运行项目测试。

不要随意使用 --no-deps 跳过依赖安装，这通常只是把安装错误推迟成运行时错误。

一套可直接使用的工作习惯​

新建项目时，可以按下面的顺序操作：

mkdir demo-project
cd demo-project
python -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -m pip check

然后记录依赖、提交依赖声明和源码，但不要提交 .venv。其他人拿到项目后，创建自己的虚拟环境并依据依赖文件安装，就能得到相近且可验证的运行环境。

最后记住三个重点：每个项目使用独立虚拟环境；通过 python -m pip 保证安装目标明确；把依赖声明纳入版本控制，才能让环境可复现。

练习​

创建一个新的练习目录并完成以下任务：

  1. 创建并启用 .venv，确认 sys.executable 指向该目录；
  2. 安装 requests，使用 pip show 找到它的版本和安装位置；
  3. 编写程序请求 https://example.com 并输出状态码；
  4. 创建 requirements.txt，在另一个全新虚拟环境中复现依赖；
  5. 执行 pip check，然后卸载 requests，观察程序再次运行时的错误；
  6. 比较发行包 beautifulsoup4 与导入名称 bs4，理解两种名称为何不能互相替代。