如何让pip优先从私有GitLab包仓库安装同名Python包？

以下是几种可行的方案，可避免重命名或设置不合理版本号的问题：

1. 调整pip源优先级：用index-url替代extra-index-url #

pip默认将extra-index-url作为主索引（PyPI）的补充，优先级更低。把私有仓库设为主索引（index-url），PyPI设为补充源（extra-index-url），就能让pip优先从私有仓库拉取包，找不到再去PyPI。

修改~/.config/pip/pip.conf：

[global]
index-url = https://你的GitLab实例地址/api/v4/projects/<项目ID>/packages/pypi/simple
extra-index-url = https://pypi.org/simple

或安装时临时指定：

pip install <自定义包名> --index-url https://你的GitLab实例地址/api/v4/projects/<项目ID>/packages/pypi/simple --extra-index-url https://pypi.org/simple

该方式对所有包生效，适合依赖大多在私有仓库、或需要全局优先私有包的场景。

2. 在requirements.txt中单独指定包的源 #

如果只有个别同名包需要优先私有仓库，无需修改全局配置，直接在requirements.txt里为目标包指定源：

# 直接指定Git仓库地址（支持分支/标签）
<自定义包名> @ git+https://你的GitLab实例地址/<组名>/<项目名>.git@v1.0.0

# 或指定私有PyPI仓库
<自定义包名> --index-url https://你的GitLab实例地址/api/v4/projects/<项目ID>/packages/pypi/simple

安装时执行pip install -r requirements.txt即可，其他包仍默认从PyPI拉取。

3. 用constraints.txt强制锁定包来源 #

创建constraints.txt文件，强制指定同名包的版本和私有仓库源：

<自定义包名>==<你的私有包版本> --index-url https://你的GitLab实例地址/api/v4/projects/<项目ID>/packages/pypi/simple

安装时通过-c参数引入约束：

pip install -r requirements.txt -c constraints.txt

这种方式能确保pip严格安装指定的私有包版本，完全不会去PyPI查找同名包。

4. 临时切换索引（按需使用） #

如果只是偶尔需要安装私有同名包，可临时将私有仓库设为唯一索引，安装完成后再恢复：

# 仅从私有仓库安装目标包（--no-deps跳过依赖安装）
pip install <自定义包名> --index-url https://你的GitLab实例地址/api/v4/projects/<项目ID>/packages/pypi/simple --no-deps
# 单独安装依赖（从PyPI拉取）
pip install -r requirements.txt --no-index --find-links=https://pypi.org/simple

该方式适合临时场景，不会影响全局配置。

内容的提问来源于stack exchange，提问作者Peter Buxton