pip3 命令详解与参数实测（Ubuntu 22.04）

目标：全面掌握 pip3 的每一个常用参数——install/--user/-r 下载安装、list/--outdated 清单巡检、show/freeze 元信息、download 离线落盘、uninstall 卸载、缓存控制、venv 隔离与 search 禁用现状，全部命令与回显已在 Ubuntu 22.04（Python 3.10.12 / pip 22.0.2）实测通过。

一、环境信息

本篇所有命令均在以下环境中逐条真实执行，回显为实际输出（非编造）：

操作系统：Ubuntu 22.04.5 LTS（x86_64），内核 6.8.0-138-generic
Python：Python 3.10.12（/usr/bin/python3）
pip：pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)，由 apt 包 python3-pip 22.0.2+dfsg-1ubuntu0.7 提供
测试数据包：cowsay==6.0（纯 Python 小包，25 kB 的 .whl，无依赖，PyPI 实时可下载）
网络出口可正常访问 PyPI（pypi.org）

python3-pip 的安装过程实录（apt 侧）：

$ DEBIAN_FRONTEND=noninteractive apt-get install --reinstall -y -qq -o Dpkg::Use-Pty=0 python3-pip; echo rc=$?
debconf: delaying package configuration, since apt-utils is not installed
(Reading database ... 26327 files and directories currently installed.)
Preparing to unpack .../python3-pip_22.0.2+dfsg-1ubuntu0.7_all.deb ...
Unpacking python3-pip (22.0.2+dfsg-1ubuntu0.7) over (22.0.2+dfsg-1ubuntu0.7) ...
Setting up python3-pip (22.0.2+dfsg-1ubuntu0.7) ...
rc=0

二、命令概览

2.1 语法与测试数据

pip3 是 Python 官方包管理器 pip 在 Debian/Ubuntu 上的入口名（明确指向 Python 3）。它面向 PyPI 生态，与 apt 管理的 deb 生态并行：

pip3 <command> [options]
pip3 install 包名[==版本]      # 从 PyPI 安装
pip3 install -r 文件           # 按 requirements 批量安装
pip3 install --user 包名       # 安装到用户目录
pip3 list [--outdated|-o]     # 已装清单与过期巡检
pip3 show 包名                # 包元信息
pip3 uninstall -y 包名        # 卸载
pip3 download 包名 -d 目录    # 只下载不安装（.whl 落盘）
pip3 freeze                   # 按锁定格式输出已装清单
pip3 check                    # 校验已装包依赖一致性

常用命令一览：

命令	作用	本文实测
`install`	在线安装（支持 `==` 锁版本）	是（3.1 节）
`install -r`	按 requirements.txt 批量装	是（3.7 节）
`install --user`	装到 ~/.local 用户目录	是（3.6 节）
`install --no-cache-dir`	禁用缓存安装	是（3.8 节）
`install --no-index --find-links`	纯本地目录离线安装	是（4.2 节）
`list` / `list --outdated` / `list -o`	清单与过期巡检	是（3.3 节）
`show`	包元信息	是（3.2 节）
`uninstall`	卸载	是（3.4 节）
`download`	下载 .whl 不安装	是（3.5 节）
`freeze`	锁定格式导出	是（4.1 节）
`check`	依赖一致性校验	是（4.3 节）
`search`	（已被 PyPI 禁用）	是（3.10 节，报错实录）
`config`	配置管理	是（3.10 节）
`--version` / `--help`	版本与帮助	是（2.2/2.3 节）

💡 技术拓展：Ubuntu 上 Python 包的落盘目录有一套 Debian 特有分层，pip3 的每个安装方式对应不同目录——

目录由谁写入场景
/usr/lib/python3/dist-packages apt（deb 包）系统自带 Python 库（如 python3-pip 自身）
/usr/local/lib/python3.10/dist-packages pip3（root 全局装） pip 管理的系统级第三方包
/root/.local/lib/python3.10/site-packages pip3 --user 当前用户私有安装
/tmp/testvenv/lib/python3.10/site-packages venv 内的 pip 虚拟环境隔离安装

Debian 系发行版把 apt 装的包放在 dist-packages（而非上游默认的 site-packages），目的就是把「系统包管理器装的」与「pip 装的」在文件层面分开，避免互相覆盖——这就是 pip3 show 的 Location 字段能区分包来源的原因。

目录	由谁写入	场景
`/usr/lib/python3/dist-packages`	apt（deb 包）	系统自带 Python 库（如 python3-pip 自身）
`/usr/local/lib/python3.10/dist-packages`	pip3（root 全局装）	pip 管理的系统级第三方包
`/root/.local/lib/python3.10/site-packages`	pip3 --user	当前用户私有安装
`/tmp/testvenv/lib/python3.10/site-packages`	venv 内的 pip	虚拟环境隔离安装

测试数据说明：cowsay==6.0 是 PyPI 上的纯 Python 命令行小包（会说话的牛），无传递依赖、体积 25 kB，适合反复装卸演示；版本号用 == 锁定，保证结果可复现。

2.2 --help 全量输出（逐行照抄）

$ pip3 --help 2>&1

Usage:   
  pip3 <command> [options]

Commands:
  install                     Install packages.
  download                    Download packages.
  uninstall                   Uninstall packages.
  freeze                      Output installed packages in requirements format.
  list                        List installed packages.
  show                        Show information about installed packages.
  check                       Verify installed packages have compatible dependencies.
  config                      Manage local and global configuration.
  search                      Search PyPI for packages.
  cache                       Inspect and manage pip's wheel cache.
  index                       Inspect information available from package indexes.
  wheel                       Build wheels from your requirements.
  hash                        Compute hashes of package archives.
  completion                  A helper command used for command completion.
  debug                       Show information useful for debugging.
  help                        Show help for commands.

General Options:
  -h, --help                  Show help.
  --debug                     Let unhandled exceptions propagate outside the
                              main subroutine, instead of logging them to
                              stderr.
  --isolated                  Run pip in an isolated mode, ignoring
                              environment variables and user configuration.
  --require-virtualenv        Allow pip to only run in a virtual environment;
                              exit with an error otherwise.
  -v, --verbose               Give more output. Option is additive, and can be
                              used up to 3 times.
  -V, --version               Show version and exit.
  -q, --quiet                 Give less output. Option is additive, and can be
                              used up to 3 times (corresponding to WARNING,
                              ERROR, and CRITICAL logging levels).
  --log <path>                Path to a verbose appending log.
  --no-input                  Disable prompting for input.
  --proxy <proxy>             Specify a proxy in the form
                              [user:passwd@]proxy.server:port.
  --retries <retries>         Maximum number of retries each connection should
                              attempt (default 5 times).
  --timeout <sec>             Set the socket timeout (default 15 seconds).
  --exists-action <action>    Default action when a path already exists:
                              (s)witch, (i)gnore, (w)ipe, (b)ackup, (a)bort.
  --trusted-host <hostname>   Mark this host or host:port pair as trusted,
                              even though it does not have valid or any HTTPS.
  --cert <path>               Path to PEM-encoded CA certificate bundle. If
                              provided, overrides the default. See 'SSL
                              Certificate Verification' in pip documentation
                              for more information.
  --client-cert <path>        Path to SSL client certificate, a single file
                              containing the private key and the certificate
                              in PEM format.
  --cache-dir <dir>           Store the cache data in <dir>.
  --no-cache-dir              Disable the cache.
  --disable-pip-version-check
                              Don't periodically check PyPI to determine
                              whether a new version of pip is available for
                              download. Implied with --no-index.
  --no-color                  Suppress colored output.
  --no-python-version-warning
                              Silence deprecation warnings for upcoming
                              unsupported Pythons.
  --use-feature <feature>     Enable new functionality, that may be backward
                              incompatible.
  --use-deprecated <feature>  Enable deprecated functionality, that will be
                              removed in the future.

帮助列出 16 个子命令与通用选项。注意 search 虽然还在列表里，实际已被 PyPI 服务端禁用（3.10 节实录）；全局选项中 --no-cache-dir、--proxy、--trusted-host 是内网环境最常用的三个。

2.3 版本信息

$ python3 --version
Python 3.10.12

$ pip3 --version
pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)

$ ls -l /usr/bin/pip /usr/bin/pip3 /usr/bin/pip3.10
-rwxr-xr-x 1 root root 221 Sep 22  2025 /usr/bin/pip
-rwxr-xr-x 1 root root 221 Sep 22  2025 /usr/bin/pip3
-rwxr-xr-x 1 root root 221 Sep 22  2025 /usr/bin/pip3.10

$ pip --version
pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)

Ubuntu 22.04 自带 Python 3.10.12 与 pip 22.0.2（随发行版更新的补丁包 22.0.2+dfsg-1ubuntu0.7）。pip、pip3、pip3.10 三个入口是 221 字节的等价包装脚本，pip --version 与 pip3 --version 输出完全一致——在只装了 Python 3 的现代 Ubuntu 上，二者可互换；习惯上脚本写 pip3 更明确（在双 Python 老系统上 pip 可能指向 Python 2）。

三、参数逐项实测

3.1 install：在线安装与落盘位置

$ pip3 install cowsay==6.0; echo rc=$?
Collecting cowsay==6.0
  Downloading cowsay-6.0-py3-none-any.whl (25 kB)
Installing collected packages: cowsay
Successfully installed cowsay-6.0
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
rc=0

$ ls /usr/local/lib/python3.10/dist-packages/ | head -6
cowsay
cowsay-6.0.dist-info

流程四步：Collecting（解析依赖并定位版本）→ Downloading（下载 .whl）→ Installing collected packages → Successfully installed。落盘两件套：cowsay/（包代码）+ cowsay-6.0.dist-info/（元数据，含 RECORD 卸载清单）——目录位于 /usr/local/lib/python3.10/dist-packages，即 2.1 节表格中「root 全局装」那一层。

末尾的 WARNING: Running pip as the 'root' user... 是 root 环境的固定提醒（建议用 venv），不影响安装结果，5.1 节展开。==6.0 锁定版本，卸掉重装版本不变，是可复现演示与生产锁版的通用写法。

💡 要点：pip3 install 生产三板斧——==版本号 锁版本（可复现）、-i 指定内部 PyPI 源（内网加速/合规）、-r requirements.txt 批量装（版本集中管理）。三者组合即「有锁文件的规范化安装」，裸 pip3 install 包名 拿最新版只适合临时试验。

3.2 show：包元信息（字段逐行解读）

$ pip3 show cowsay
Name: cowsay
Version: 6.0
Summary: The famous cowsay for GNU/Linux is now available for python
Home-page: https://github.com/VaasuDevanS/cowsay-python
Author: Vaasudevan Srinivasan
Author-email: vaasuceg.96@gmail.com
License: GNU-GPL
Location: /usr/local/lib/python3.10/dist-packages
Requires: 
Required-by:

关键字段：Version（当前装的确切版本）、Location（安装目录——由此判断包是 apt 装的还是 pip 装的、装在全局还是用户目录，见 2.1 节分层表）、Requires/Required-by（依赖关系两个方向，排障时可快速定位「谁依赖它/它依赖谁」）。cowsay 无依赖，两个依赖字段为空。

💡 要点：pip3 show 是排查「import 报错找不到模块」的第一跳——先看 Location 确认包装在了哪一层（系统全局/用户目录/venv），再确认当前 python3 会不会扫到该目录；Location 缺失说明包根本没装上（此时 show 返回 rc=1）。Required-by 非空时卸载前必须先处理依赖方。

3.3 list / --outdated / -o：清单与过期巡检

$ pip3 list | grep -i cowsay
cowsay        6.0

$ pip3 list | head -5
Package       Version
------------- -------
cowsay        6.0
dbus-python   1.2.18
distro        1.7.0
ERROR: Pipe to stdout was broken
Exception ignored in: <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>
BrokenPipeError: [Errno 32] Broken pipe

$ pip3 list --outdated 2>&1 | head -6
Package       Version Latest Type
------------- ------- ------ -----
cowsay        6.0     6.1    wheel
dbus-python   1.2.18  1.5.0  sdist
distro        1.7.0   1.9.0  wheel
pip           22.0.2  26.2.1 wheel

$ pip3 list -o 2>&1 | head -3
Package       Version Latest Type
------------- ------- ------ -----
cowsay        6.0     6.1    wheel

list 两列（Package/Version），会同时列出 apt 装的带元数据的包（dbus-python、distro 就是 deb 侧来的）；--outdated 联网比对 PyPI 最新版，四列（Package/Version/Latest/Type），-o 是它的短选项等价形式。可见 pip 22.0.2 本身已有 26.2.1 新版——系统 pip 是否要自升级见 5.3 节。

注意 pip3 list | head 结尾的 BrokenPipeError 报错：Python 程序被 head 提前关闭管道时把异常打到 stderr，清单本身完整（与 dpkg-deb 处理 SIGPIPE 的方式不同），属无害现象，5.2 节展开。

💡 要点：pip3 list 会把 apt 装的 Python 库也列进来（两套包体系共用同一 site 目录），但只能卸 pip 自己装的——对 deb 侧来的包执行 uninstall 会连 apt 的登记一起破坏。区分归属看 pip3 show 的 Location：dist-packages 多为 apt 装、site-packages 多为 pip 装；deb 侧包请用 apt remove 管理。

3.4 uninstall：卸载

$ pip3 uninstall -y cowsay; echo rc=$?
Found existing installation: cowsay 6.0
Uninstalling cowsay-6.0:
  Successfully uninstalled cowsay-6.0
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
rc=0

$ pip3 show cowsay 2>&1; echo rc=$?
WARNING: Package(s) not found: cowsay
rc=1

-y 跳过确认（不带 -y 会列出将删除的文件清单并等待输入 y/n，脚本必须带 -y）。卸载依据是 dist-info/RECORD 清单，删得干净：复查 show 输出 Package(s) not found，退出码 1。

💡 要点：pip 的 RECORD 清单机制让卸载比 apt 更「精确到文件」，但它只删 RECORD 里登记的文件——运行时生成的缓存/数据目录（如 ~/.cache/cowsay）不会被清理，彻底清场需手工排查。pip3 uninstall 不支持批量通配，多个包要空格逐个列出。

3.5 download：把 .whl 下载到目录（不安装）

$ pip3 download cowsay==6.0 -d /tmp/wheels 2>&1 | tail -2
Saved /tmp/wheels/cowsay-6.0-py3-none-any.whl
Successfully downloaded cowsay

$ ls -lh /tmp/wheels
total 28K
-rw-r--r-- 1 root root 25K Oct 15 23:04 cowsay-6.0-py3-none-any.whl

-d 指定落盘目录，cowsay-6.0-py3-none-any.whl 即纯 Python 通用 wheel（py3-none-any 标签）。download 只下载不安装，是离线安装链（4.2 节）与内网分发的第一步；若包有依赖，依赖的 .whl 会一并下载。

💡 要点：离线分发的标准链路是「联网机 download → 拷贝 .whl → 离线机 install」；download 会自动带上全部依赖的 .whl，拷贝时一个都不能少。py3-none-any 标签说明纯 Python 无平台绑定——带 C 扩展的包标签形如 cp310-cp310-manylinux_2_17_x86_64，跨机器分发时要确认目标机的 Python 版本与 glibc 匹配，否则 install 阶段报「not a supported wheel」。

3.6 install --user：装到用户目录

$ python3 -m site --user-base
/root/.local

$ pip3 install --user cowsay==6.0 2>&1 | tail -2
Successfully installed cowsay-6.0
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

$ ls /root/.local/lib/python3.10/site-packages/
cowsay
cowsay-6.0.dist-info

$ pip3 show cowsay | grep -i location
Location: /root/.local/lib/python3.10/site-packages

$ pip3 uninstall -y cowsay
Found existing installation: cowsay 6.0
Uninstalling cowsay-6.0:
  Successfully uninstalled cowsay-6.0
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

$ ls /root/.local/lib/python3.10/site-packages/ 2>&1

--user 的落盘规则：~/.local/lib/python<版本>/site-packages（对照 python3 -m site --user-base 的输出）。show 的 Location 随之变为用户目录，验证安装位置切换成功；卸载后目录清空。用户目录安装不需要 root、不影响系统全局，适合多用户服务器上各自维护工具链。

💡 要点：--user 安装的命令入口落在 ~/.local/bin/——该目录默认在 PATH 里，但优先级高于 /usr/local/bin，同名工具会遮蔽系统版本（which -a 工具名 可查遮蔽链）。多用户服务器上 pip3 install --user 造成的「为什么我的命令行为和 root 不一样」大多源于此。

3.7 install -r：requirements.txt 批量安装

$ printf 'cowsay==6.0\n' > /tmp/requirements.txt; cat /tmp/requirements.txt
cowsay==6.0

$ pip3 install -r /tmp/requirements.txt 2>&1 | tail -2
Successfully installed cowsay-6.0
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

$ pip3 show cowsay | head -2
Name: cowsay
Version: 6.0
ERROR: Pipe to stdout was broken
Exception ignored in: <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>
BrokenPipeError: [Errno 32] Broken pipe

$ pip3 uninstall -y cowsay
Found existing installation: cowsay 6.0
Uninstalling cowsay-6.0:
  Successfully uninstalled cowsay-6.0
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

requirements.txt 每行一条声明（包名==版本、>=、~= 等写法，可加注释），install -r 按行解析安装——生产部署的标准入口。文件生成推荐用 pip3 freeze > requirements.txt（4.1 节实测），保证版本逐字锁定。

💡 要点：三种约束符语义不同——== 锁死单版本、>= 只设下限、~= 兼容区间；生产锁版一律 == 或直接用 freeze 输出，裸包名（无约束）等于每次拿最新，重建环境时不可复现。-r 支持嵌套（requirements 里再 -r 另一个文件），多环境部署用它做分层清单。

3.8 缓存与 --no-cache-dir

$ du -sh /root/.cache/pip 2>&1
464K	/root/.cache/pip

$ pip3 install --no-cache-dir cowsay==6.0 2>&1 | tail -2
Successfully installed cowsay-6.0
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

$ pip3 uninstall -y cowsay
Found existing installation: cowsay 6.0
Uninstalling cowsay-6.0:
  Successfully uninstalled cowsay-6.0
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

pip 下载过的 .whl 会缓存到 ~/.cache/pip（本环境 464K），重复安装同版本时回显会显示 Using cached ... 而不是 Downloading ...。--no-cache-dir 让本次安装跳过缓存读写——下载大包、或缓存疑似损坏时使用；也可以 --cache-dir 目录 改放位置。CI/构建机常用 --no-cache-dir 控制构建产物体积。

💡 要点：~/.cache/pip 是纯缓存，整目录 rm -rf 零风险（下次重新下载）；回显里 Using cached ... 是命中缓存的提速标志而非异常。取舍口诀：交互机器留缓存提速，CI/一次性构建加 --no-cache-dir 省盘。

3.9 venv：python3 -m venv 隔离环境（含 ensurepip 报错实录）

Ubuntu 最小安装不带 venv 组件，首次创建会得到这段经典报错：

$ python3 -m venv /tmp/testvenv; echo rc=$?
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.10-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

Failing command: /tmp/testvenv/bin/python3

rc=1

按提示补装（apt 侧素材），重建成功：

$ DEBIAN_FRONTEND=noninteractive apt-get install -y -qq -o Dpkg::Use-Pty=0 python3.10-venv >/dev/null 2>&1; echo install_rc=$?
install_rc=0

$ python3 -m venv /tmp/testvenv; echo rc=$?
rc=0

$ /tmp/testvenv/bin/pip --version
pip 22.0.2 from /tmp/testvenv/lib/python3.10/site-packages/pip (python 3.10)

$ /tmp/testvenv/bin/pip install cowsay==6.0 2>&1 | tail -2
Installing collected packages: cowsay
Successfully installed cowsay-6.0

$ /tmp/testvenv/bin/pip list | head -6
Package    Version
---------- -------
cowsay     6.0
pip        22.0.2
setuptools 59.6.0

$ pip3 show cowsay 2>&1; echo rc=$?
WARNING: Package(s) not found: cowsay
rc=1

$ rm -rf /tmp/testvenv; echo cleaned
cleaned

隔离证明闭环：venv 内的 pip 装了 cowsay（venv list 可见），系统侧 pip3 show 完全看不到（Package(s) not found）——venv 的 site-packages 与系统 dist-packages 互不可见，这正是项目级依赖管理的价值。venv 本身就是普通目录，rm -rf 即彻底删除。

💡 要点：venv 的隔离是「目录级」的——激活只改 PATH 与 VIRTUAL_ENV 环境变量，deactivate 退出；venv 内 pip3/python3 都指向 venv 目录，装的东西外界不可见（本节 show 实证）。ensurepip 报错的根因是 python3-venv 系统包未装（Ubuntu 默认不装），apt install python3-venv 一次性补齐。

3.10 search：已禁用的命令（实录）与 config

$ pip3 search cowsay 2>&1; echo rc=$?
ERROR: XMLRPC request failed [code: -32500]
RuntimeError: PyPI no longer supports 'pip search' (or XML-RPC search). Please use https://pypi.org/search (via a browser) instead. See https://warehouse.pypa.io/api-reference/xml-rpc.html#deprecated-methods for more information.
rc=1

pip search 在 pip 帮助里仍在，但 PyPI 已于 2020 年起逐步关停 XMLRPC 搜索接口，pip 22 时代执行必然得到上述 ERROR: XMLRPC request failed [code: -32500]。替代方案：网页版 https://pypi.org/search ，或 pip3 index versions 包名（pip 22.2+ 提供，本版 22.0.2 尚无）。

config 用于管理 pip 配置（镜像源、代理等），未配置时输出为空、rc=0：

💡 要点：pip search 已随 PyPI XMLRPC 接口关停而全局禁用，选型查询改走浏览器（pypi.org）或 pip index versions 包名（列全部可用版本）。pip config list 是排查「源到底配在哪一层」的快速手段——用户级与全局级同名配置按就近覆盖。

$ pip3 config list 2>&1; echo rc=$?
rc=0

配置文件位置按层级：全局 /etc/pip.conf、用户 ~/.config/pip/pip.conf（旧式 ~/.pip/pip.conf 亦被识别）、venv 内 venv/pip.conf。国内服务器最常见的用法是在用户级配置里写入 PyPI 镜像源的 index-url。

3.11 技术拓展：pip 生态同类工具对比

Python 包管理工具不止 pip 一家，主流选项横向对比——

工具	定位	依赖解析	适用场景
pip	官方标准安装器	递归安装，无统一锁文件	单包/requirements.txt 安装，最通用
pip + pip-tools	pip 增强（pip-compile/pip-sync）	生成带哈希的锁定 requirements	需要「确定性安装」的生产部署
venv（标准库）	环境隔离（配合 pip）	同 pip	项目级依赖隔离，零额外安装
conda / miniconda	跨语言包+环境管理	有独立求解器	科学计算栈（二进制依赖复杂时）
poetry	项目管理全合一	有 lock 文件（poetry.lock）	应用项目开发-打包-发布一体
uv	Rust 实现的新一代 pip 替代	极快解析 + uv.lock	追求安装速度的新项目（较新）

💡 关键差异一句话：pip 是唯一随 Python 官方分发的标准，其余工具都围绕它做「锁版本、提速或环境管理」的增强。本文以系统自带的 pip 22.0.2 + venv 为主线（Ubuntu 22.04 开箱即用、零额外依赖）；生产部署建议在 pip 基础上引入 pip-tools 或 poetry 生成锁文件，把「装哪个版本」从手工锁 == 升级为机器可复核的清单。

四、实战示例

4.1 freeze 生成依赖锁文件

场景：把当前环境已装的 pip 包导出成锁定清单，供部署机 install -r 复现：

$ pip3 freeze | head -6
dbus-python==1.2.18
distro==1.7.0
PyGObject==3.42.1
ssh-import-id==5.11

$ pip3 freeze | wc -l
4

freeze 输出与 list 的差别：一律 包名==版本 格式（可直接回灌给 -r），且只列带 pip 元数据的包——本机 4 条全是 apt 装的 deb 附带的（dbus-python 等），纯 pip 装的包此时已卸载所以不在列。生产惯例：项目 venv 里 pip3 freeze > requirements.txt，交付时 pip3 install -r requirements.txt 精确复现。

4.2 离线安装链（download → --no-index --find-links）

场景：内网机器无 PyPI 访问。外网机先 download，再拷贝目录到内网机离线安装：

$ pip3 download cowsay==6.0 -d /tmp/wheels 2>&1 | tail -1
Successfully downloaded cowsay

$ pip3 install --no-index --find-links=/tmp/wheels cowsay==6.0 2>&1 | tail -2
Successfully installed cowsay-6.0
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

$ pip3 show cowsay | grep Location
Location: /usr/local/lib/python3.10/dist-packages

$ pip3 check; echo rc=$?
pygobject 3.42.1 requires pycairo, which is not installed.
rc=1

$ pip3 uninstall -y cowsay 2>&1 | tail -1
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

--no-index 禁用全部在线索引，--find-links=/tmp/wheels 只认本地目录——组合起来是 pip 的离线安装标准形态，回显中不会有 Downloading（全部命中本地 .whl）。装完顺手 pip3 check 做依赖一致性校验。

4.3 pip3 check 排障：发现 pip 元数据的依赖缺口

场景：服务器例行健康检查，pip3 check 报了一条真实的依赖缺口：

$ pip3 check; echo rc=$?
pygobject 3.42.1 requires pycairo, which is not installed.
rc=1

解读：PyGObject（apt 的 python3-gi 包附带）在 pip 元数据里声明依赖 pycairo，但 pycairo 是以系统库形式由 deb 提供的，pip 看不到——这是「apt 装的 Python 包」与「pip 依赖树」之间的经典错位，不代表系统真的坏。处置原则：确认对应 deb 包（python3-gi-cairo）是否已装，装齐后此告警即消失；不要为了消警贸然 pip3 install pycairo 把系统库又覆盖一层。这条命令的价值在于给纯 pip 环境做一致性体检（rc=0 才是干净态）。

4.4 --user 与 venv 的选型对照

两种隔离方式本文均已实测，选型对照：

维度	pip3 install --user（3.6 节）	python3 -m venv（3.9 节）
落盘位置	`~/.local/lib/python3.10/site-packages`	`<venv>/lib/python3.10/site-packages`
隔离范围	用户级（所有项目共享该用户目录）	项目级（一项目一 venv）
依赖版本冲突	同一包只能一个版本	各 venv 独立版本，互不干扰
创建成本	无需额外组件	需 python3.10-venv（Ubuntu 默认不带，3.9 节实录）
适用	单机自用小工具	任何正式项目

结论：临时给当前用户装个 CLI 工具用 --user；正式项目一律 venv，requirements.txt 跟随项目走。

五、注意事项与常见问题

Q1：每次 install/uninstall 结尾都有 WARNING: Running pip as the 'root' user...，要紧吗？ 要紧程度分场景：root 全局装会写 /usr/local，可能与 apt 管理的同名包互相覆盖，pip 官方因此提醒改用 venv。处理：临时用一下可忽略（回显不受影响）；正式项目按 3.9 节上 venv；确实需要系统级第三方包时保持 == 锁版本并记录清单（4.1 节）。

Q2：pip3 list | head / pip3 show 包名 | head 结尾的 ERROR: Pipe to stdout was broken / BrokenPipeError 是坏了吗？ 不是。head 读完前几行就关闭管道，Python 把 SIGPIPE 以 BrokenPipeError 异常打印到 stderr（3.3/3.7 节实录）。被截断的那部分数据仍完整有效。规避：用 pip3 list | sed -n '1,5p' 之类读完整个输出的方式，或无视该报错。

Q3：系统自带的 pip 22.0.2 能不能 pip3 install --upgrade pip 自升级？ 能跑但不建议。升级后新版 pip 会装进 /usr/local/lib/python3.10/dist-packages 并接管 /usr/bin/pip3，与 apt 包 python3-pip 的后续更新产生两套来源（2.1 节分层正是为了避免这种覆盖）。系统 pip 交给 apt 更新即可；项目需要新 pip 时在 venv 内升级，随项目隔离。

Q4：pip3 search 必然报错吗？ 是。PyPI 已关停 XMLRPC 搜索接口，任何 pip search 都会得到 ERROR: XMLRPC request failed [code: -32500]（3.10 节实录）。找包用网页 https://pypi.org/search ，版本查询用 pip3 index versions 包名（需 pip 22.2+）。

Q5：装在 --user 与系统目录的同名包，实际用哪个？ Python 导入路径的优先级是：venv > 用户目录（~/.local）> 系统目录（/usr/local 优先于 /usr/lib）。同名包多层共存时以最内层为准，pip3 show 包名 的 Location 能确认当前命中的是哪一层。卸载时 pip 也只卸当前层的那份，必要时逐层清理。

Q6：pip3 说找不到包/连接超时？ 先分清两件事：WARNING: Package(s) not found 是「已装清单里没有」（卸载/查询场景）；ERROR: Could not find a version that satisfies the requirement 才是「PyPI 上找不到或网络不通」。后者排查顺序：网络出口 → 是否需要 --proxy/--trusted-host → 国内环境配置镜像源（3.10 节 config）→ 包名拼写与 Python 版本兼容性（旧 pip 对新包的元数据格式可能不识别）。

六、参考链接

pip 官方文档 · 用户指南（install/freeze/requirements）：https://pip.pypa.io/en/stable/user_guide/
pip 官方文档 · CLI 命令参考：https://pip.pypa.io/en/stable/cli/pip/
Python 官方教程 · venv 虚拟环境：https://docs.python.org/3/tutorial/venv.html
PyPI XMLRPC 接口弃用公告（pip search 禁用原因）：https://warehouse.pypa.io/api-reference/xml-rpc.html
Ubuntu Debian 打包 · dist-packages 说明（python3 packaging）：https://wiki.debian.org/Python