pip 使用与配置参数详解

目标：系统梳理 pip 的配置文件、各层级位置与优先级、国内源配置、常用命令（install/download/list/show/freeze/uninstall/cache/wheel）的常用参数、配置参数中文解释、环境变量方式与常见问题。本文档所有命令与回显均为 Ubuntu 22.04 实测结果。

环境信息

操作系统：Ubuntu 22.04（x86_64）
Python：Python 3.10.12（/usr/bin/python3、/usr/bin/python3.10）
pip：初始 22.0.2，升级后 26.2.1（/usr/local/lib/python3.10/dist-packages/pip）
已配置国内源（清华 TUNA）：https://pypi.tuna.tsinghua.edu.cn/simple
已安装包（实测）：requests、six、jmespath、python-dateutil、pytz、ptyprocess、urllib3、certifi、charset_normalizer、idna、setuptools、wheel 等
默认缓存目录：/root/.cache/pip

配置文件

配置文件的位置与优先级

pip 配置文件为 .ini 格式，按「环境变量 > 命令参数 > 文件配置」的优先级读取。文件配置本身又分多层级，低层级的用户配置文件会覆盖高层级系统配置。

各级别文件位置（通过 pip config debug 实测获取）如下：

层级	文件位置（实测）	生效范围	优先级
全局 global	`/etc/pip.conf`、`/etc/xdg/pip/pip.conf`	所有用户	低
站点 site	`/usr/pip.conf`	site-packages 同级别	↓
用户 user	`~/.pip/pip.conf`、`~/.config/pip/pip.conf`	当前用户	高（覆盖全局）

注意：pip config set（不带层级参数）默认写入 ~/.config/pip/pip.conf；而手动新建时常用 ~/.pip/pip.conf。二者都会出现在 pip config debug 的 user: 之下，且 ~/.pip/pip.conf 优先于 ~/.config/pip/pip.conf 被读取。

用 pip config 查看各层级及完整列表

# 查看当前所有生效配置（相邻 key 相同取高优先级）
pip config list

# 查看每个层级的文件是否存在及其中各项
pip config debug

实测回显（各层级文件探查）：

$ pip config debug
env_var:
env:
global:
  /etc/xdg/pip/pip.conf, exists: False
  /etc/pip.conf, exists: False
site:
  /usr/pip.conf, exists: False
user:
  /root/.pip/pip.conf, exists: True
    global.index-url: https://pypi.tuna.tsinghua.edu.cn/simple
    install.trusted-host: pypi.tuna.tsinghua.edu.cn
  /root/.config/pip/pip.conf, exists: False

$ pip config list
global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
install.trusted-host='pypi.tuna.tsinghua.edu.cn'

分级别查看（--user / --global / --site）

pip config list --user     # 只看用户级
pip config list --global   # 只看全局级
pip config list --site     # 只看站点级
pip config list -v         # verbose，列出将尝试加载的每个文件

实测回显：

$ pip config list --user
global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
install.trusted-host='pypi.tuna.tsinghua.edu.cn'

$ pip config list --global
$ pip config list --site

$ pip config list -v
For variant 'global', will try loading '/etc/xdg/pip/pip.conf'
For variant 'global', will try loading '/etc/pip.conf'
For variant 'user', will try loading '/root/.pip/pip.conf'
For variant 'user', will try loading '/root/.config/pip/pip.conf'
For variant 'site', will try loading '/usr/pip.conf'
global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
install.trusted-host='pypi.tuna.tsinghua.edu.cn'

用 pip config set / get / unset 管理配置

不手写文件，也可用命令读写配置项（此写法默认写入 ~/.config/pip/pip.conf）：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 回显：Writing to /root/.config/pip/pip.conf

pip config get global.index-url
# 回显：https://pypi.tuna.tsinghua.edu.cn/simple

pip config unset global.timeout
# 回显：ERROR: No such key - global.timeout   （key 不存在时提示）

完整的 pip.conf 示例（含中文注释）

# 全局段：影响所有命令的通用配置
[global]
# 下载源地址（PyPI 镜像）
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
# 额外备用的下载源（多源按序查找）
extra-index-url =
    https://mirrors.aliyun.com/pypi/simple/
# 请求超时秒数（默认 15）
timeout = 30
# 失败重试次数（默认 5）
retries = 5
# 走代理（http://user:pass@host:port）
proxy = http://127.0.0.1:7890
# 缓存目录
cache-dir = /root/.cache/pip
# 关闭 pip 版本自检提示
disable-pip-version-check = true
# 关闭进度条/彩印的非交互场景
no-input = true

# install 段：仅影响 pip install
[install]
# 对该主机跳过 SSL 校验（仅用于自建 http 源/内网源）
trusted-host =
    pypi.tuna.tsinghua.edu.cn
    mirrors.aliyun.com
# 要求必须在虚拟环境中安装（防止污染系统）
require-virtualenv = false
# 允许写入系统 Python 环境（PEP 668 externally-managed 时用）
break-system-packages = true

国内源配置

常用国内镜像

镜像	index-url
清华大学 TUNA	`https://pypi.tuna.tsinghua.edu.cn/simple`
阿里云	`https://mirrors.aliyun.com/pypi/simple/`
腾讯云	`https://mirrors.cloud.tencent.com/pypi/simple/`
中科大 USTC	`https://pypi.mirrors.ustc.edu.cn/simple/`

方式一：写入配置文件（推荐，持久生效）

mkdir -p ~/.pip
cat > ~/.pip/pip.conf <<'EOF'
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

验证：

$ pip config list
global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
install.trusted-host='pypi.tuna.tsinghua.edu.cn'

方式二：命令行临时指定（仅本次，不写文件）

# 单次安装用阿里云源
pip install requests -i https://mirrors.aliyun.com/pypi/simple/

# 等价写法 --index-url
pip install requests --index-url https://mirrors.aliyun.com/pypi/simple/

实测（以阿里云为 index-url 安装）：

$ pip install -i https://mirrors.aliyun.com/pypi/simple/ --no-deps python-dateutil
  Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)
Installing collected packages: python-dateutil
Successfully installed python-dateutil-2.9.0.post0

方式三：环境变量（会话级）

export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
export PIP_TRUSTED_HOST=pypi.tuna.tsinghua.edu.cn

实测环境变量覆盖（PIP_INDEX_URL 指定阿里云后，config list 增加一条 :env: 前缀项）：

$ PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ pip config list
global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
install.trusted-host='pypi.tuna.tsinghua.edu.cn'
:env:.index-url='https://mirrors.aliyun.com/pypi/simple/'

$ PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ pip config debug | head -4
env_var:
  PIP_INDEX_URL='https://mirrors.aliyun.com/pypi/simple/'
env:

常用命令详解

pip install（安装 / 更新）

参数	作用	示例
`-i` / `--index-url`	指定下载源	`pip install -i https://mirrors.aliyun.com/pypi/simple/ pkg`
`--extra-index-url`	追加额外下载源	`pip install --extra-index-url https://mirrors.aliyun.com/pypi/simple/ pkg`
`--trusted-host`	跳过某主机 SSL 校验	`pip install --trusted-host mirrors.aliyun.com pkg`
`-r <file>`	从 requirements 文件批量安装	`pip install -r requirements.txt`
`-U` / `--upgrade`	升级到最新版	`pip install -U six`
`--user`	安装到用户目录 `~/.local`	`pip install --user pkg`
`--force-reinstall`	强制重装（忽略已装版本）	`pip install --force-reinstall six`
`--no-deps`	只装包本身不装依赖	`pip install --no-deps pkg`
`--target <dir>`	装到指定目录	`pip install --target /root/mylib pkg`
`--no-index`	不使用索引源	常与 `--find-links` 联用离线安装
`--find-links <dir>`	从本地目录/页面查找包	`pip install --no-index --find-links=/root/offline pkg`
`--no-cache-dir`	不使用本地缓存	`pip install --no-cache-dir pkg`
`--dry-run`	只解析不实际安装	`pip install --dry-run pkg`
`--require-virtualenv`	非虚拟环境则报错中止	`pip install --require-virtualenv pkg`
`--break-system-packages`	允许覆盖系统环境（PEP 668）	`pip install --break-system-packages pkg`
`--no-input`	禁止交互输入	适合脚本/CI

实测（多参数）：

# --trusted-host 内网/自建 http 源场景（此处用清华测试）
$ pip install --trusted-host pypi.tuna.tsinghua.edu.cn ptyprocess
Installing collected packages: ptyprocess
Successfully installed ptyprocess-0.7.0

# --target 装到指定目录
$ pip install --target /root/mylib jmespath
Successfully installed jmespath-1.1.0
$ ls /root/mylib/            # bin  jmespath  jmespath-1.1.0.dist-info

# -U 升级（已是最新会提示 already satisfied）
$ pip install -U six
Requirement already satisfied: six in /usr/local/lib/python3.10/dist-packages (1.17.0)

# --force-reinstall 强制重装
$ pip install --force-reinstall six
Successfully installed six-1.17.0

# --require-virtualenv 非虚拟环境
$ pip install --require-virtualenv pytz
ERROR: Could not find an activated virtualenv (required).

# --extra-index-url 多源并行查找
$ pip install --extra-index-url https://mirrors.aliyun.com/pypi/simple/ --dry-run pytz
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple, https://mirrors.aliyun.com/pypi/simple/
Requirement already satisfied: pytz in /usr/local/lib/python3.10/dist-packages (2026.4)

# --dry-run 只试运行不安装
$ pip install --dry-run pytz
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Requirement already satisfied: pytz in /usr/local/lib/python3.10/dist-packages (2026.4)

⚠️ root 用户下 pip 26 会打印 "Running pip as the 'root' user ... Use the --root-user-action option" 的提示警告，这是安全提示而非错误，可用 --root-user-action=ignore 抑制。

⚠️ 关于 --import：pip install 没有 --import 参数（任务排查确认）。若执行 pip install --import 会直接输出用法帮助而非执行。实际「从 requirements 读取」是 -r；而 --report 选项取值 auto/disabled/import/editables 中的 import 是指报告导入机制，与安装参数无关。向外部读者澄清，避免误用。

pip download（下载包与依赖，不安装）

参数	作用	示例
`-d` / `--dest` / `--dest-dir`	下载到指定目录	`pip download -d /root/offline jmespath`
`--no-deps`	只下载包本身	`pip download --no-deps -d dir pkg`
`-r <file>`	按 requirements 文件批量下载	`pip download -r requirements.txt -d dir`
`-i` / `--index-url`	指定下载源	`pip download -i 镜像 pkg`
`--platform`	限定目标平台架构	`pip download --platform win_amd64 ...`
`--python-version`	限定目标 Python 版本	`pip download --python-version 311 ...`
`--only-binary=:all:`	只下 binary（wheel）	`pip download --only-binary=:all: ...`
`--no-index --find-links`	从本地目录下载	内网场景

实测（下载 jmespath / python-dateutil 及其依赖到 /root/offline）：

$ pip download -d /root/offline jmespath python-dateutil
Collecting python-dateutil
  Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)
Collecting six>=1.5 (from python-dateutil)
  Using cached six-1.17.0-py2.py3-none-any.whl (11 kB)
Saved ./root/offline/jmespath-1.1.0-py3-none-any.whl
Saved ./root/offline/python_dateutil-2.9.0.post0-py2.py3-none-any.whl
Saved ./root/offline/six-1.17.0-py2.py3-none-any.whl
Successfully downloaded jmespath python-dateutil six

$ ls /root/offline/
jmespath-1.1.0-py3-none-any.whl
python_dateutil-2.9.0.post0-py2.py3-none-any.whl
six-1.17.0-py2.py3-none-any.whl

实测（跨平台：为 Windows + Python 3.11 下载 wheel）：

$ pip download --platform win_amd64 --python-version 311 --only-binary=:all: --dest /root/winpkgs pip>=23
$ ls /root/winpkgs/
pip-26.2.1-py3-none-any.whl

pip list（列出已装包）

参数	作用
`-o` / `--outdated`	只列出有可用新版的包
`-u` / `--uptodate`	只列出已是最新的包
`--not-required`	只列出顶层包（不被其他包依赖的）
`--format=columns / json / freeze`	输出格式

实测：

$ pip list --outdated
Package    Version Latest Type
---------- ------- ------ -----
setuptools 59.6.0  84.0.0 wheel
wheel      0.37.1  0.48.0 wheel

$ pip list --not-required
Package         Version
--------------- -----------
jmespath        1.1.0
pip             26.2.1
ptyprocess      0.7.0
python-dateutil 2.9.0.post0
pytz            2026.4
requests        2.34.2

pip show（查看包详情）

参数	作用
`-f` / `--files`	额外列出包安装的文件列表

实测：

$ pip show requests
Name: requests
Version: 2.34.2
Summary: Python HTTP for Humans.
Home-page:
Author:
Author-email: Kenneth Reitz <me@kennethreitz.org>
License: Apache-2.0
Location: /usr/local/lib/python3.10/dist-packages
Requires: certifi, charset_normalizer, idna, urllib3
Required-by:

$ pip show -f requests
Location: /usr/local/lib/python3.10/dist-packages
Requires: certifi, charset_normalizer, idna, urllib3
Required-by:
Files:
...

pip freeze（导出已装包为 requirements）

实测（导出当前环境 requests 相关依赖为 /root/requirements.txt）：

$ pip freeze
certifi==2026.7.22
charset-normalizer==3.5.1
idna==3.20
requests==2.34.2
six==1.17.0
urllib3==2.8.0

$ pip freeze > /root/requirements.txt
$ cat /root/requirements.txt
certifi==2026.7.22
charset-normalizer==3.5.1
idna==3.20
requests==2.34.2
six==1.17.0
urllib3==2.8.0

⚠️ pip freeze 会含 pip/setuptools/wheel 自身吗？实测不包含（本机 freeze 未列出 pip 26.2.1）。它只输出非基础工具包。

pip uninstall（卸载）

参数	作用
`-y` / `--yes`	跳过确认直接卸载
`-r <file>`	按 requirements 文件批量卸载
一次性传多个包名	批量卸载

实测：

$ pip uninstall -y tzdata
  Successfully uninstalled tzdata-2026.4

$ pip uninstall -y requests certifi charset-normalizer idna urllib3
  Successfully uninstalled charset-normalizer-3.5.1
  Successfully uninstalled idna-3.20
  Successfully uninstalled urllib3-2.8.0

pip cache（缓存管理）

子命令	作用
`pip cache dir`	显示缓存目录
`pip cache list`	列出本地构建的 wheel 缓存
`pip cache info`	显示缓存统计（HTTP 页 + wheel）
`pip cache purge`	清空缓存
`pip cache remove <pattern>`	按关键字删除

实测：

$ pip cache dir
/root/.cache/pip

$ pip cache info
Package index page cache location (pip v23.3+): /root/.cache/pip/http-v2
Package index page cache location (older pips): /root/.cache/pip/http
Package index page cache size: 3.0 MB
Number of HTTP files: 22
Locally built wheels location: /root/.cache/pip/wheels
Locally built wheels size: 0 bytes
Number of locally built wheels: 0

$ pip cache purge
Files removed: 22 (3.0 MB)
Directories removed: 79

pip wheel（打包为 wheel）

参数	作用
`-w` / `--wheel-dir <dir>`	输出 wheel 目录
`-r <file>`	按 requirements 批量打包
`--no-deps`	只打包本身

实测：

$ pip wheel --wheel-dir ./root/wheels jmespath
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Collecting jmespath
  Downloading jmespath-1.1.0-py3-none-any.whl (20 kB)
Saved ./root/wheels/jmespath-1.1.0-py3-none-any.whl

# 批量（按 requirements）
$ pip wheel -r /root/requirements.txt -w /root/allwheels
Saved ./root/allwheels/requests-2.34.2-py3-none-any.whl
Saved ./root/allwheels/urllib3-2.8.0-py3-none-any.whl
Saved ./root/allwheels/six-1.17.0-py2.py3-none-any.whl
$ ls /root/allwheels/
certifi-2026.7.22-py3-none-any.whl
charset_normalizer-3.5.1-cp310-cp310-manylinux2014_x86_64...whl
idna-3.20-py3-none-any.whl
requests-2.34.2-py3-none-any.whl
six-1.17.0-py2.py3-none-any.whl
urllib3-2.8.0-py3-none-any.whl

pip check / pip search

pip check 校验依赖完整性：

$ pip check
No broken requirements found.

pip search 已被 PyPI 废弃移除。实测：

$ pip search requests
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.

替代方案：前往 https://pypi.org/search 网页检索。

命令实战示例

示例 A：安装依赖 → 导出 → 离线安装全流程

# 1) 联网机安装开发者所需的包
pip install jmespath python-dateutil

# 2) 导出当前环境
pip freeze > requirements.txt

# 3) 下载全部依赖（含传递依赖）到离线目录
mkdir -p /root/offline
pip download -r requirements.txt -d /root/offline

# 4) 目标机（无外网）从本地离线安装
pip install --no-index --find-links=/root/offline -r requirements.txt

示例 B：离线目录安装（--no-index + --find-links）

# 卸载后演示纯离线
$ pip uninstall -y jmespath python-dateutil
  Successfully uninstalled python-dateutil-2.9.0.post0

$ pip install --no-index --find-links=/root/offline jmespath python-dateutil
Processing ./root/offline/python_dateutil-2.9.0.post0-py2.py3-none-any.whl
Installing collected packages: python-dateutil, jmespath
Successfully installed jmespath-1.1.0 python-dateutil-2.9.0.post0

$ python3 -c "import jmespath, dateutil; print('offline import ok: jmespath', jmespath.__version__)"
offline import ok: jmespath 1.1.0

示例 C：直接安装本地 wheel 文件

$ pip install /root/offline/jmespath-1.1.0-py3-none-any.whl
jmespath is already installed with the same version as the provided wheel.
Use --force-reinstall to force an installation of the wheel.
# 已装同版本时给出该提示，加上 --force-reinstall 即可重装

# 只装包、不装依赖：
$ pip install --no-deps /root/offline/python_dateutil-2.9.0.post0-py2.py3-none-any.whl

示例 D：requirements.txt 批量回灌（-r 装回，已验证 import）

$ pip uninstall -y six
  Successfully uninstalled six-1.17.0

$ pip install -r /root/requirements.txt
Installing collected packages: six
Successfully installed six-1.17.0

$ python3 -c "import six; print('six ok ->', six.__version__)"
six ok -> 1.17.0

配置参数详解

以下为常见可配置项的中文解释（均可写入 [global]，也可通过 -- 命令行或 PIP_ 前缀环境变量设置）。

配置键	默认值	说明	示例
`index-url`	`https://pypi.org/simple`	包索引网址（下载源）	`index-url = https://pypi.tuna.tsinghua.edu.cn/simple`
`extra-index-url`	空	附加索引源（默认先查 index-url 再查它）	见上文 pip.conf 示例
`trusted-host`	空	该主机不校验证书（允许 http/自签）	`trusted-host = mirrors.aliyun.com`
`timeout`	15（秒）	单次网络请求超时	`timeout = 30`
`retries`	5	网络失败重试次数（0 为不重试）	`retries = 3`
`proxy`	空	指定代理服务器	`proxy = http://127.0.0.1:7890`
`cache-dir`	平台默认	缓存目录	`cache-dir = /root/.cache/pip`
`no-cache-dir`	false	禁用磁盘缓存	`no-cache-dir = true`
`disable-pip-version-check`	false	关闭「有新版本 pip」提醒	`disable-pip-version-check = true`
`require-virtualenv`	false	要求必须处于虚拟环境才安装	`require-virtualenv = true`
`default-timeout`	15（秒）	timeout 的别名，连接/读取默认超时	`default-timeout = 30`
`break-system-packages`	false	允许覆盖系统 Python 环境（PEP 668 externally-managed）	`break-system-packages = true`
`no-input`	false	禁止任何交互输入（脚本/CI 用）	`no-input = true`
`no-cache-dir`	false	同 `no-cache-dir`	—

说明：default-timeout 与 timeout 等同义，均映射到 pip 的超时配置（默认 15 秒）。

环境变量方式

pip 所有配置项都有对应的环境变量，规则为「配置键大写、- 换成 _、前缀 PIP_」：index-url → PIP_INDEX_URL，no-cache-dir → PIP_NO_CACHE_DIR，trusted-host → PIP_TRUSTED_HOST，cache-dir → PIP_CACHE_DIR。

export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
export PIP_TRUSTED_HOST=pypi.tuna.tsinghua.edu.cn
export PIP_NO_CACHE_DIR=1
export PIP_TIMEOUT=30

实测（环境变量读写与缓存目录）：

$ PIP_NO_CACHE_DIR=1 pip config list -v | grep no-cache
:env:.no-cache-dir='1'

$ PIP_CACHE_DIR=/root/cachetest pip cache dir
/root/cachetest

优先级（高 → 低）：命令行参数 > 环境变量 > 配置文件。

常见问题（FAQ / 排障）

Q1：`pip config set` 写到了哪？为什么我手写在 `~/.pip` 没生效？

pip config set 默认写入 ~/.config/pip/pip.conf；而手动新建一般放 ~/.pip/pip.conf。两者同为 user 级，~/.pip/pip.conf 优先。若你在两个文件都配了同 key，pip config list 会各打印一行（实测即如此，见下）。排查用 pip config debug。

实测（重复配置场景）：

$ cat /root/.pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn

$ cat /root/.config/pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn

$ pip config list      # 两个文件都含同 key → 各打一行
global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
install.trusted-host='pypi.tuna.tsinghua.edu.cn'
global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
install.trusted-host='pypi.tuna.tsinghua.edu.cn'

# 删除其中一个即可回到单条配置

Q2：`pip install` 报 `ERROR: Could not find a version that satisfies the requirement ...`

现象：安装不存在的包名时报此错。实测：

$ pip install --break-system-packages resolver-lite
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
ERROR: Could not find a version that satisfies the requirement resolver-lite (from versions: none)
ERROR: No matching distribution found for resolver-lite

定位/解决：包名拼写错误或源中没有该包；改用 -i 指定正确的源，或核对 PyPI 上的包名。

Q3：root 下安装提示 "Running pip as the 'root' user"？

定位：pip 的安全提示。解决：改用虚拟环境；或在 [global] 加 root-user-action = ignore（或命令 --root-user-action=ignore）抑制。

Q4：`--user` 安装显示 already satisfied？

实测（root 场景）：

$ pip install --user ptyprocess
Requirement already satisfied: ptyprocess in /usr/local/lib/python3.10/dist-packages (0.7.0)

定位：包已装到全局 site-packages，--user 默认复用；以普通用户 + 无全局副本时才会真正装到 ~/.local。建议优先使用虚拟环境。

Q5：`pip search` 不可用？

解决：pip search 已被 PyPI 移除，改用浏览器 https://pypi.org/search。

Q6：pip 太旧如何升级？

python3 -m pip install --upgrade pip

升级后 pip 会从 /usr/lib/python3/dist-packages/pip 变为 /usr/local/lib/python3.10/dist-packages/pip（Ubuntu 上的正常现象）。

参考链接

pip 官方文档：https://pip.pypa.io/en/stable/
pip 配置（pip.conf）：https://pip.pypa.io/en/stable/topics/configuration/
pip 缓存说明：https://pip.pypa.io/en/stable/topics/caching/
清华 TUNA PyPI 镜像：https://tuna.tsinghua.edu.cn/help/pypi/
阿里云 PyPI 镜像：https://developer.aliyun.com/mirror/pypi
PyPI 网页搜索：https://pypi.org/search

pip 使用与配置参数详解

pip 使用与配置参数详解

环境信息

配置文件

配置文件的位置与优先级

用 pip config 查看各层级及完整列表

分级别查看（--user / --global / --site）

用 pip config set / get / unset 管理配置

完整的 pip.conf 示例（含中文注释）

国内源配置

常用国内镜像

方式一：写入配置文件（推荐，持久生效）

方式二：命令行临时指定（仅本次，不写文件）

方式三：环境变量（会话级）

常用命令详解

pip install（安装 / 更新）

pip download（下载包与依赖，不安装）

pip list（列出已装包）

pip show（查看包详情）

pip freeze（导出已装包为 requirements）

pip uninstall（卸载）

pip cache（缓存管理）

pip wheel（打包为 wheel）

pip check / pip search

命令实战示例

示例 A：安装依赖 → 导出 → 离线安装全流程

示例 B：离线目录安装（--no-index + --find-links）

示例 C：直接安装本地 wheel 文件

示例 D：requirements.txt 批量回灌（-r 装回，已验证 import）

配置参数详解

环境变量方式

常见问题（FAQ / 排障）

Q1：pip config set 写到了哪？为什么我手写在 ~/.pip 没生效？

Q2：pip install 报 ERROR: Could not find a version that satisfies the requirement ...

Q3：root 下安装提示 "Running pip as the 'root' user"？

Q4：--user 安装显示 already satisfied？

Q5：pip search 不可用？

Q6：pip 太旧如何升级？

参考链接

Q1：`pip config set` 写到了哪？为什么我手写在 `~/.pip` 没生效？

Q2：`pip install` 报 `ERROR: Could not find a version that satisfies the requirement ...`

Q4：`--user` 安装显示 already satisfied？

Q5：`pip search` 不可用？