如何在requirement.txt中引入自托管Jfrog PyPI仓库的wheel文件

直接按下面步骤配置即可，完全兼容Docker镜像构建场景，不会影响公共依赖的正常安装。

1. requirements.txt 正确写法 #

核心是用--extra-index-url指定私有仓库地址，不要替换pip默认的公共PyPI源，私有包和公共依赖的写法完全一致，不需要给私有包单独加URL。

# 追加私有Artifactory PyPI源为额外拉取源，注意路径必须是simple结尾的标准PyPI API地址
--extra-index-url https://<你的内网Artifactory域名>/artifactory/api/pypi/<你的PyPI仓库名>/simple

# 你的私有wheel包，和公共依赖写法完全一致，填包名+对应版本即可
your-private-package==1.0.0
# 其余公共依赖正常罗列，不需要做任何修改
requests==2.32.0
fastapi==0.110.0
uvicorn==0.29.0
pydantic==2.6.4

注意：绝对不要用--index-url指向你的私有仓库，这个参数会覆盖pip默认的公共PyPI源，所有公共依赖都会被强制从私有仓库拉取，如果你的私有仓库没配置公网PyPI代理缓存，会直接出现大量包找不到的安装错误。

2. 鉴权配置（适配Docker构建场景） #

自托管Artifactory一般都开启了访问权限控制，不要把账号密码硬编码在requirements.txt或者Dockerfile里，用Docker构建参数传入凭证即可，凭证不会留在最终镜像层。

配套Dockerfile示例 #

FROM python:3.12-slim

# 定义构建时传入的鉴权参数，不会持久化到最终镜像
ARG ARTIFACTORY_USER
ARG ARTIFACTORY_API_KEY

WORKDIR /opt/app
COPY requirements.txt .

# 安装依赖时动态拼接带鉴权信息的源地址
RUN pip install --no-cache-dir \
    --extra-index-url https://${ARTIFACTORY_USER}:${ARTIFACTORY_API_KEY}@<你的内网Artifactory域名>/artifactory/api/pypi/<你的PyPI仓库名>/simple \
    -r requirements.txt

COPY . .
CMD ["python", "main.py"]

镜像构建命令 #

构建时通过--build-arg传入你在Artifactory后台生成的账号和API Key即可：

docker build \
  --build-arg ARTIFACTORY_USER=你的内网账号 \
  --build-arg ARTIFACTORY_API_KEY=你在Artifactory个人中心生成的API密钥 \
  -t your-app:v1 .

常见踩坑排查 #

• 私有包拉取失败先核对包名：你上传的wheel文件名需要符合PyPI命名规范，pip会自动兼容中划线、下划线的命名差异，重点核对版本号和你打包时配置的版本完全一致。
• 要是你们团队需要统一管控所有Python依赖（包括公共包），可以在Artifactory里创建PyPI类型的虚拟仓库，同时聚合本地私有仓库、公网PyPI远程代理仓库，这时候可以直接把--index-url指向这个虚拟仓库地址，所有依赖都会走Artifactory拉取，公共包会被Artifactory自动缓存，适合企业级安全扫描、版本统一管控的场景。
• 构建前先确认Docker构建环境的网络能正常访问内网Artifactory地址，避免防火墙、安全组拦截导致的连接超时。
• 优先用Artifactory生成的API Key做鉴权，不要直接用登录密码，后续密钥轮换不需要修改业务配置，只需要调整构建时传入的参数即可。

内容的提问来源于stack exchange，提问作者Tolulope Olorunfemi