Pip 使用简易指南

pip 是 Python 的包管理工具，用于第三方库的查找、下载、安装、卸载等。

从 Python 3.4 开始，pip 默认包含在 Python 二进制安装程序中。如果安装的 Python 版本里没有自带 pip 工具，可以通过下载 get-pip.py 文件，然后通过如下方式安装:

python get-pip.py install pip

运行 pip 可以通过 pip 命令，也可以用 python -m pip 来完成：

$ pip --version
pip 21.3.1 from /usr/local/lib/python3.8/dist-packages/pip (python 3.8)
$ python -m pip --version
pip 21.3.1 from /usr/local/lib/python3.8/dist-packages/pip (python 3.8)
$ /bin/python3 -m pip --version
pip 21.3.1 from /usr/local/lib/python3.8/dist-packages/pip (python 3.8)

使用 /bin/python3 -m pip 这样的方式运行 pip 是比较推荐的方式，因为在你的系统里可能存在多个 Python 环境，这样运行可以显式的指示为哪个环境使用 pip。pip 命令的语法格式为：

python -m pip  [options]

一些常用的公共的参数：

--debug  启动 DEBUG 模式
-v, --verbose  显示更加详细的
-q, --quiet  显示更少的信息
--log   将输出记录到文件
--proxy   指定代理服务器，格式为 [user:passwd@]proxy.server:port
--retries   指定最大的尝试次数，默认为 5 次
--timeout   指定超时时间，默认为 15 秒
--cache-dir   指定缓存目录
--no-cache-dir  禁用缓存

Install

pip 默认从 PyPI 下载包并安装，其基本用法为：

pip install [options]  [package-index-options] ...
pip install [options] -r  [package-index-options] ...
pip install [options] [-e]  ...
pip install [options] [-e]  ...
pip install [options]  ...

从 PyPI 下载包时，pip 使用 HTTP simple interface 查找相应的包。除了从 PyPI 下载包安装外，pip 还支持从本地文件、本地项目目录、压缩包、远程路径（url）安装。

安装包时的常用参数：

-r, --requirement   指定依赖说明文件
--no-deps  不安装依赖
--pre  包含预发布版本或开发测试版本，默认只搜索稳定版
-e, --editable   以可编辑模式安装，通常用于开发调试本地项目
--user  安装到用户目录下，通常为 ~/.local/
-U, --upgrade  升级指定的包及其依赖
--force-reinstall  强制重装指定包
-I, --ignore-installed  忽略已经安装的包
-i, --index-url   指定包仓库的索引地址，即所谓的源，默认为 https://pypi.org/simple
--extra-index-url  额外的包仓库索引地址
--no-index  忽略包仓库地址（通常与 --find-links 配合使用，实现离线安装）
--find-links  指定查找路径，可以是一个本地路径，或者一个 HTML 文件链接

pip 支持从 版本控制系统 VCS（version control systems）安装包，这种支持需要系统中存在相应 VCS 的可执行文件，且需要在 URL 前加上相应前缀：

• Git -- git+
• Mercurial -- hg+
• Subversion -- svn+
• Bazaar -- bzr+

例如 Git 支持的格式为 git+file, git+https, git+ssh, git+http 等等。

可以将需要安装的包写在一个依赖描述文件中，用 -r 参数指定该文件位置，pip 会解析该文件并安装合适的包，该文件通常被命名为 requirements.txt。依赖描述文件示例：

# Requirement Specifiers:

pkg
pkg == 1.3
pkg >=1.2,<2.0
pkg == 1.*     # 模糊匹配，表示 1 版本均可，如 1.1, 1.2
okg!=1.3.5     # 除了 1.3.5 版本，其他版本均可
pkg~=1.4.2     # 兼容的版本，即大于 1.4.2 的 1.4 版本均可，类似 >= 1.4.2, == 1.4.*
pkg[foo, bar]  # 指定额外的依赖项

# 支持环境标志
pkg ==5.4 ; python_version < '3.8'
pkg; sys_platform == 'win32'

# 直接包含一个文件路径
./downloads/pkg-1.0.2-cp38-none-win32.whl
http://pkg.com/pkg-1.0.8-cp38-none-win_amd64.whl

# 从 git 仓库安装
git+https://github.com/hello/project.git
git+https://github.com/hello/project.git

一些安装示例：

# 指定包和版本
pip install pkg
pip install pkg==1.0.4
pip install 'pkg>=1.0.4'

# 指定依赖说明文件
pip install -r requirements.txt

# 升级包
pip install --upgrade pkg
pip install -U pkg

# 以编辑模式安装本地项目
pip install -e .
pip install --pre -e .   # 允许预发布版本
pip install -e path/to/project

# 只安装指定包，不安装其依赖
pip instal --no-deps pkg

# 安装到用户目录，而不是系统默认目录
pip install --user pkg

# 指定安装目录前缀
pip install --install-option="--prefix=/usr/local" pkg

# 从 Git 仓库安装
pip install git+ssh://git.example.com/project#egg=project
pip install git+file:///home/user/projects/project#egg=project
pip install git+https://git.example.com/project#egg=project

# 安装额外的依赖项
pip install pkg[PDF]
pip install "pkg[PDF] @ git+https://git.repo/pkg@main#subdirectory=subdir_path"
pip install .[PDF]  # project in current directory
pip install pkg[PDF]==3.0
pip install pkg[PDF,EPUB]  # multiple extras

# 安装时不使用二进制包
pip install pkg1 pkg2 --no-binary :all:  # 所有包都不使用二进制
pip install pkg1 pkg2 --no-binary pkg1   # 仅 pkg1 不使用二进制

# 从指定的仓库源安装
pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple/ pkg

# 从指定路径安装：
pip install --no-index --find-links=file:///local/dir/ pkg
pip install --no-index --find-links=/local/dir/ pkg
pip install --no-index --find-links=relative/dir/ pkg

如果安装时指定了错误的版本，则会报错：

$ pip install requests==lemon
Looking in indexes: https://mirrors.aliyun.com/pypi/simple/
ERROR: Could not find a version that satisfies the requirement requests==lemon (from versions: 0.2.0, ... 2.26.0)
ERROR: No matching distribution found for requests==lemon

所以，可以通过这种方式来查看可用的版本，直接运行 pip intall numpy== （不指定任何版本号）也可以达到同样的效果。

此外，还可以使用 download 命令，只下载包到本地，而不安装，如：

# 下载包
pip download pkg

# 下载包到指定目录
pip download -d /tmp pkg

# 允许预发布版本，且不下载依赖
pip download --no-deps --pre pkg

# 从指定源下载
pip download -i https://pypi.tuna.tsinghua.edu.cn/simple/ pkg

需要卸载已安装的包，则使用 uninstall 命令：

# 卸载包
pip uninstall pkg

# 不用手动确认，直接卸载
pip uninstall -y pkg

# 卸载 requirements.txt 文件列出的包
pip uninstall -r requirements.txt

Wheel

Wheel 是 Python 的达标标准，这之前的主流打包格式是 egg 文件。Wheel 遵循 PEP-0427 标准，其本质是一个 zip 压缩文件，zip应用程序打开它。打包与安装 Wheel 文件都依赖 wheel 库，需要先安装它：

pip install wheel

制作 wheel 文件可以使用 pip wheel 命令，如：

pip wheel --wheel-dir=~/whl .

--wheel-dir 指定生成 .whl 文件的存储位置，最后指定包含 setup.py 文件的项目目录，示例中指定了当前目录。

在项目目录中可以将安装依赖写入到 requirements.txt 文件中，然后用 -r 参数指定，在制作 .whl 安装包时会将 requirements.txt 里的安装依赖写入到 dist-info 里的 METADATA 文件中：

pip wheel --wheel-dir=~/whl -r requirements.txt .

也可以直接在项目目录中使用 setup.py 的 bdist_wheel 命令制作 wheel 文件：

python setup.py bdist_wheel

安装 wheel 文件时直接指定 .whl 文件位置即可：

pip install ~/whl/pkg-1.0.0-py3-none-any.whl

如果是在 windows 环境下，安装一些需要编译的包可能不是很容易，可以到 https://www.lfd.uci.edu/~gohlke/pythonlibs/ 下载已经编译好的 whl 文件安装。

List

list 命令由于列出已安装的包，常用的参数有：

-o, --outdated    列出可更新的包
-u, --uptodate    列出已经更新到最新版本的包
-e, --editable    列出所有可编辑的项目
-l, --local       只列出在虚拟环境中安装的包，也就是不列出全局安装的包
--user            只列出用户级别安装的包
--pre             包含预发布的版本和开发版本，默认情况下只包含稳定版本
--format          指定输出格式，包括 columns(默认), freeze, json 或 legacy

使用示例：

$ pip list
Package                                           Version
------------------------------------------------- -------------------
alabaster                                         0.7.12
altair                                            4.1.0
...

$ pip list --format=json
[{"name": "alabaster", "version": "0.7.12"}, ...]

$ pip list --format=freeze
alabaster==0.7.12
altair==4.1.0
...

freeze 输出格式与使用 freeze 命令是同样的效果：

$ pip freeze
alabaster==0.7.12
altair==4.1.0
...

freeze 命令通常用于将环境导出为 requirements.txt，以便用 -r 安装指定安装：

# 导出环境
pip freeze > requirements.txt

# 恢复环境
pip install install -r requirements.txt

还可以使用 show 命令查看已安装包的信息:

# 查看包信息
pip show pkg

# 查看包信息，同时列出安装的文件
pip show -f pkg
pip show --files pkg

Config

config 命令可以用于管理配置，其基本用法为：

pip config [] list
pip config [] [--editor ] edit

pip config [] get name
pip config [] set name value
pip config [] unset name
pip config [] debug

选项参数包括：

--global  使用系统全局配置
--user  使用用户配置
--site  使用当前虚拟环境配置
--editor   指定编辑器

示例（配置源）：

pip config set global.index-url http://mirrors.aliyun.com/pypi/simple/
pip config set install.trusted-host mirrors.aliyun.com

设置的配置会写入相应的配置文件中，也可以手动修改配置文件来完成配置。各平台下的配置文件位置，Unix 环境：

类型	位置
Global	/etc/pip.conf
User	$HOME/.config/pip/pip.conf
Site	$VIRTUAL_ENV/pip.conf

MacOS 环境：

类型	位置
Global	/Library/Application Support/pip/pip.conf
User	$HOME/.config/pip/pip.conf
Site	$VIRTUAL_ENV/pip.conf

Windows 环境：

类型	位置
Global	C:\ProgramData\pip\pip.ini
User	%APPDATA%\pip\pip.ini
Site	$VIRTUAL_ENV/pip.conf

此外，pip 在各平台上都会优先加载 PIP_CONFIG_FILE 环境变量指定的配置，pip 加载配置文件的

• PIP_CONFIG_FILE
• Global
• User
• Site

配置文件示例：

[global]
quiet = 0
verbose = 2
timeout = 60
no-cache-dir = false
index-url = https://pypi.tuna.tsinghua.edu.cn/simple/

[install]
ignore-installed = true
no-dependencies = yes

[freeze]
timeout = 10

Mirror

常用镜像地址：

• 官方： https://pypi.org/
• 豆瓣： https://pypi.doubanio.com/simple/
• 阿里云： https://mirrors.aliyun.com/pypi/simple/
• 腾讯云： https://mirrors.cloud.tencent.com/pypi/simple/
• 华为云： https://mirrors.huaweicloud.com/repository/pypi/simple/
• 清华大学： https://pypi.tuna.tsinghua.edu.cn/simple/
• 中国科学技术大学： https://pypi.mirrors.ustc.edu.cn/simple/
• 华中理工大学： https://pypi.hustunique.com/
• 山东理工大学： https://pypi.sdutlinux.org/

更多使用方式可查阅 pip 官网文档：pip documentation v22.0.4