如何通过Poetry在pyproject.toml中添加GitLab私有包依赖

要从GitLab包注册表安装依赖到Poetry项目，有两种更规范的配置方式，替代直接拉取Git仓库的做法：

方法1：配置项目级私有仓库（推荐） #

这种方式把GitLab包注册表作为项目的私有源，所有依赖可以统一管理，且避免硬编码令牌。

步骤1：在pyproject.toml中添加私有仓库配置 #

# 定义GitLab私有包仓库
[tool.poetry.repositories.gitlab-private]
url = "https://gitlab.com/api/v4/projects/<project_id>/packages/pypi/simple"

# 添加依赖时指定使用该仓库
[tool.poetry.dependencies]
python = "^3.8"
<my_package> = { version = ">=1.0.0,<2.0.0", index = "gitlab-private" }

注意：替换<project_id>为你的GitLab项目ID，<my_package>为包名，版本号根据实际需求指定范围，不要用*。

步骤2：配置仓库认证 #

不要直接在配置文件里写令牌，用Poetry命令设置认证（令牌会存在本地配置，不会提交到代码仓库）：

# 设置仓库的用户名和令牌（GitLab要求用户名为__token__）
poetry config http-basic.gitlab-private __token__ <your_personal_token>

或者用环境变量更安全（适合CI/CD场景）：

export POETRY_HTTP_BASIC_GITLAB_PRIVATE_USERNAME=__token__
export POETRY_HTTP_BASIC_GITLAB_PRIVATE_PASSWORD=<your_personal_token>

方法2：单个依赖直接指定索引（快速临时方案） #

如果只需要给单个依赖指定源，可以直接在依赖项里写完整索引地址，但不推荐硬编码令牌：

[tool.poetry.dependencies]
<my_package> = { version = ">=1.0.0", index = "https://__token__:<your_personal_token>@gitlab.com/api/v4/projects/<project_id>/packages/pypi/simple" }

警告：这种方式会把令牌暴露在配置文件中，仅用于临时测试，不要提交到版本仓库。

关键注意事项 #

• 你的GitLab个人令牌必须拥有read_package_registry权限，在GitLab个人设置的「访问令牌」页面生成。
• 使用包注册表的优势：安装速度更快（无需克隆整个仓库）、支持预编译wheel包、依赖版本与GitLab发布的包版本完全对应。

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