Python pip 教程：安装包、管理版本与使用 PyPI

pip 到底是什么

pip 是用来安装别人写的 Python 库的工具。当你运行 pip install requests 时，它会在 PyPI（Python Package Index）上查找 requests，下载适合你平台的版本，并放到 Python 安装目录下的 site-packages 文件夹中。之后，import requests 就能正常工作了。

无论是从 python.org、Homebrew 还是 Linux 包管理器安装的 Python 3，都已经自带 pip。在安装任何东西之前，先确认一下：

python -m pip --version

你应该会看到一个版本号和 pip 模块的路径。如果命令失败，最可靠的修复方法是：

python -m ensurepip --upgrade

它会用解释器自带的副本，把 pip 安装到你的 Python 中。

python -m pip 与 pip

这两种写法你都会见到。它们的作用几乎相同，但有一个重要区别：python -m pip 使用的是 PATH 上的 python，也就是你的脚本所用的那个。单独的 pip 用的是最先被找到的那个 pip，两者并不总是同一个。

当你装了不止一个 Python 时（在 macOS 上很容易出现这种情况），单独使用 pip 就会导致这种让人困惑的局面：“我明明装了这个库，代码却还是报 ModuleNotFoundError。”

经验法则：当你想确定包会装到哪个解释器时，使用 python -m pip ...。如果你很确定，快速操作时用单独的 pip 也没问题。

安装包

基本命令：

python -m pip install requests

它会从 PyPI 获取 requests 及其所有依赖，并把它们安装好。一分钟后你就可以使用它了：

# This runs in your browser - the Coddy runtime ships with requests.
import requests

response = requests.get("https://httpbin.org/json")
print(response.status_code)
print(response.json())

一次安装多个包：

python -m pip install requests pandas rich

固定特定版本：

python -m pip install "django==5.0.2"
python -m pip install "requests>=2.30,<3"

在某些 shell 中，引号很重要：它们能防止 == 和 < 被当作 shell 运算符解析。

升级与卸载

python -m pip install --upgrade requests
python -m pip uninstall requests

--upgrade 会获取满足你所指定约束的最新版本。uninstall 会删除这个包，但不会删除它的依赖；这些依赖会一直保留，直到你显式地删除它们。

让 pip 本身保持最新：

python -m pip install --upgrade pip

值得每隔几个月运行一次。新版 pip 能发现更多安装问题，依赖解析也做得更好。

查看已安装的包

python -m pip list
python -m pip show requests

list 会显示当前 Python 中安装的所有包。show requests 会打印这个包的版本、位置、依赖和许可证。当你想知道“我实际用的到底是哪个版本”时，它很有用。

requirements.txt：把依赖记录下来

当项目用到的库不止一两个时，就把清单记下来。pip freeze 可以帮你做到：

python -m pip freeze > requirements.txt

它会生成一个文件，每行一个固定版本的依赖：

django==5.0.2
requests==2.31.0
rich==13.7.1

任何克隆了你仓库的人都可以用下面的命令重现安装：

python -m pip install -r requirements.txt

pip freeze 会记录所有已安装的东西，包括间接依赖。要精确重现环境，这样没问题；但如果你只想要代码真正导入的顶层库，它就显得太杂了。很多项目会手动维护一个只包含直接依赖的 requirements.txt，让 pip 去解析间接依赖。

在现代项目中，pyproject.toml（搭配 pip-tools、uv、poetry 或 hatch 等工具）正在取代 requirements.txt。思路是一样的，“把依赖写下来，运行一条命令安装它们”，只是文件格式更结构化。

始终安装到虚拟环境中

每个正经的 Python 项目都应该有一个虚拟环境。它是项目本地的一个文件夹，有自己的 python 和自己安装的包，所以在一个项目里 pip install 不会影响其他项目。

两行就能搭好：

python -m venv .venv
source .venv/bin/activate    # macOS / Linux
# or .venv\Scripts\activate on Windows

激活之后，python -m pip install requests 会把包安装到 venv 中。系统的 Python 保持干净。我们在虚拟环境页面中有更深入的介绍。

如果你运行 pip install 时看到关于安装到系统 Python 的警告（或者提示你加上 --break-system-packages），请停下来。这说明你应该创建一个 venv。

pip 无法安装包时

几种常见的失败情况及其含义：

• Could not find a version that satisfies the requirement …：通常是包名拼错了，或者这个包需要比你当前更新的 Python 版本。
• error: Microsoft Visual C++ 14.0 or greater is required（Windows）：这个包带有原生扩展，需要 C++ 构建工具链。要么安装 Microsoft 的 Build Tools，要么找一个预编译好的 wheel（大多数热门包都会提供）。
• Permission denied：你试图在没有 root 权限的情况下安装到系统 Python。正确的修复方法不是 sudo pip install，而是使用虚拟环境。
• 安装后出现 ModuleNotFoundError：几乎总是因为 pip install 把包装到了另一个 Python 里，而不是运行你脚本的那个。请检查 which python 和 which pip（macOS/Linux），或者 where python / where pip（Windows）。更可靠的做法是使用 python -m pip install ...。

pip 的现代替代工具

你会看到有人提到下面这些工具，它们都兼容 pip，各自解决特定的痛点：

• uv：快得多的安装和依赖解析工具。大多数 pip 命令都可以直接用它替换。
• pipx：把命令行工具（比如 black、ruff、httpie）安装到各自独立的 venv 中，这样它们可以全局使用，又不会和项目依赖冲突。
• poetry 和 hatch：项目管理工具，把虚拟环境管理、依赖解析和构建集成到一个工具里。

刚开始学的时候，这些你都用不上。先学会 pip；等到它们解决的痛点成为你的痛点时，再去用它们。

下一步：虚拟环境

包和虚拟环境是分不开的。你已经知道了原因；下一页会详细介绍 venv：创建、激活、退出，以及让 Python 项目保持条理的一些小约定。