详解pip install

pip install 主要是用来安装第三方依赖的：

• 如果是安装符合当前OS（mac，linux，Windows）、硬件架构（x86_64, arm64）、版本，并且是构建好的依赖（.whl, .tar.gz），可以直接安装。
• 否则只能下载源码进行构建安装，通常需要pyproject.toml(setup.py, setup.cfg)指定包的构建信息和位置。如果包里面有c，c++，rust等等，系统还需要有指定的编译器（gcc，clang，msvc）

具体而言，后面的参数可以分为下面几类

1. 包的来源 (Package Sources)

这是最核心的部分，定义了 pip 从哪里去获取要安装的包。

来源类型	格式与示例	说明
PyPI 包名	pip install requests pip install 'requests>=2.20.0,<3.0.0'	最常用的方式。从 Python 官方包索引 (Python Package Index， PyPI) 下载。可以指定精确版本、最小版本、范围等。
版本控制系统 (VCS)	pip install git+https://... pip install hg+https://... pip install svn+https://... pip install bzr+lp:proj	从 Git, Mercurial, Subversion, Bazaar 等仓库直接安装。在git中，后面还可以跟上tag， branch， 哈希来指明具体的版本（Commit）。
指定分支/标签/提交	pip install git+https://... @main pip install git+https://... @v1.2.3 pip install git+https://... @a1b2c3d	在VCS安装的基础上，可以指定分支 (@branch_name)、标签 (@tag_name) 或提交哈希 (@commit_hash)。
本地项目目录	pip install . pip install ./my_project_dir	直接从本地文件系统上的一个包含 pyproject.toml 或 setup.py 的项目源代码目录进行安装。
本地归档文件	pip install ./package-1.0.whl pip install ./package-1.0.tar.gz	直接安装本地已经下载好的 Wheel (预构建) 或 sdist (源码) 归档文件，常用于离线安装。
远程归档文件URL	pip install https://.../package-1.0.whl pip install https://.../package-1.0.tar.gz	从一个指定的URL下载归档文件并安装。

2. 通过文件进行批量管理

当需要安装多个包时，手动一个个输入会很繁琐，这时就需要用文件来管理。

文件类型	格式与示例	说明
需求文件 (Requirement)	pip install -r requirements.txt pip install --requirement requirements.txt	这是管理项目依赖的核心功能。pip 会读取这个文本文件，并安装里面列出的所有包。文件中的每一行都可以是上面“包的来源”中提到的任何一种格式。
约束文件 (Constraint)	pip install -c constraints.txt	它与需求文件类似，但只规定版本，不直接触发安装。它用于确保环境中所有依赖项的版本符合一个统一的规范，通常与 -r 配合使用，以实现可复现的构建。

3. 特殊安装模式

这些模式会改变 pip 的安装行为。

模式	格式与示例	说明
可编辑模式 (Editable)	pip install -e . pip install --editable ./my_project_dir	对开发者极其重要。它不会把代码复制到 site-packages，而是在那里创建一个指向你源代码位置的链接。这样，你修改源代码后，无需重新安装就能立即生效。

4. 常用的附加选项/标志 (Flags)

这些选项用于微调安装过程。

选项/标志	格式与示例	说明
升级包	pip install --upgrade requests pip install -U requests	将指定的包升级到 PyPI 上可用的最新版本。
指定包索引	pip install -i https://pypi.tuna.tsinghua.edu.cn/simple requests	-i 或 --index-url。临时使用指定的包索引（镜像源），而不是官方的 PyPI。对于国内用户可以显著提速。
忽略依赖	pip install --no-deps requests	只安装指定的包，完全不安装它的任何依赖项。用于想手动控制依赖的特殊场景。
指定安装目录	pip install --target ./libs requests	-t 或 --target。将包安装到一个指定的目录，而不是系统或用户的 site-packages 目录。常用于打包发布（如 AWS Lambda）。
用户模式安装	pip install --user requests	将包安装到用户的主目录 (~/.local/) 下，而不是系统全局目录。这样不需要管理员权限，且不会影响系统级的 Python 环境。
预览操作	pip install --dry-run requests	模拟安装过程，显示将会安装什么包，但实际上不执行任何安装操作。

5. 安装本质

pip install 的核心任务是解析并安装包及其依赖。它的执行流程大致如下：

1. 寻找合适的发行版：pip 会首先在包索引（默认为 PyPI）上寻找与当前 Python 环境（版本、操作系统、架构）匹配的预编译 wheel (.whl) 文件。
2. 下载与安装：
   • 如果找到了 wheel 文件，pip 会直接下载并解压到指定位置，通常是当前 Python 环境的 site-packages 目录下。
   • 如果没有找到合适的 wheel 文件，pip 会下载源码发行版 (.tar.gz 或 .zip)，然后在本地尝试编译和构建，最后再将构建产物安装到 site-packages 目录。
3. 递归解析依赖：在安装主包的同时，pip 会读取包的元数据，找出它的所有依赖包，并为这些依赖包重复上述过程，直到所有“依赖的依赖”都被满足。

需要注意的重点：

• 依赖冲突：在安装新包时，其依赖可能与环境中已安装的包版本不兼容, 尤其是在递归解析依赖的阶段，pip 可能会升级或降级某些包，这有可能会“破坏”原有项目所需的版本。强烈建议使用虚拟环境（如 venv）来隔离不同项目的依赖，避免此类问题。
• 源码构建：从源码构建可能需要本地安装特定的编译器（如 GCC, MSVC++）和开发库。如果安装某个包时看到大量的编译错误信息，通常就是这个原因。

综合示例

pip install 命令的组合能力非常强大，例如：

# 从一个包含多个包（包括一个git仓库）的需求文件安装，
# 同时使用清华镜像源，并将所有包升级到最新版本
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple -U

requirements.txt 文件内容可能如下：

# requirements.txt
pandas>=1.5.0
numpy==1.23.5
git+https://github.com/GeeeekExplorer/nano-vllm.git@main