python项目管理poetry，如何配置镜像？国内加速地址

我们相信：世界是美好的，你是我也是。 来玩一下解压小游戏吧！

对于python来说，poetry才是【大项目】的标志。所以，以后还是要多多使用poetry才对。poetry对标的是pip，使用上和npm命令比较相似。本文描述poetry如何配置镜像地址，都有哪些镜像地址可选。

苏南大叔的“程序如此灵动”博客，记录苏南大叔的代码编程经验总结。测试环境：win10，python@3.12.9，pip@25.0.1，poetry@2.1.2。

先说一下本文结论：poetry和pip两者的镜像地址是通用的，区别仅仅在于配置方式不一样。

常见镜像地址

pip 的镜像地址可以用于 Poetry，因为 Poetry 也使用 PyPI 仓库来安装依赖。你可以直接将 pip 的镜像地址（如清华源、阿里云源等）配置到 Poetry 中。以下是一些常见的pip/Poetry镜像地址：

参考文章：

• https://newsn.net/say/pip-mirror.html
• https://newsn.net/say/conda-mirror.html

配置文件位置

关于poetry命令的基本情况，可以参考：

• https://newsn.net/say/python-poetry.html

对于本文的“配置poetry镜像地址”这件事情来说，有三个文件是需要注意的。

• 项目根目录下的pyproject.toml文件。【局部项目镜像，改这个】
• %APPDATA%\pypoetry\下的全局配置文件poetry.toml。【全局项目镜像，改这个】
• 项目根目录下面的配置文件poetry.toml。【不动，不改它】

全局镜像

全局镜像地址适用于所有使用Poetry的项目。

• 修改的文件是：%APPDATA%\pypoetry\下的全局配置文件poetry.toml。
• 通常来说是：C:\Users\<用户名>\AppData\Roaming\pypoetry\poetry.toml。

命令行配置

运行以下命令，将镜像地址设置为清华源：

poetry config repositories.pypi https://pypi.tuna.tsinghua.edu.cn/simple

改回去默认的pypi源的话，可以删除配置文件。或者执行：

poetry config repositories.pypi https://pypi.org/simple

手动编辑

编辑全局配置文件 poetry.toml，添加镜像地址：

[repositories]
pypi = { url = "https://pypi.tuna.tsinghua.edu.cn/simple" }

全局多镜像

[repositories]
pypi = { url = "https://pypi.tuna.tsinghua.edu.cn/simple" }
custom = { url = "https://custom-mirror.example.com/simple" }

项目镜像地址

编辑的文件是项目根目录下面的pyproject.toml，这里也有不同的编辑方式（结果）：

命令行配置

在项目目录下运行以下命令：

poetry source add --priority=primary tuna https://pypi.tuna.tsinghua.edu.cn/simple/

手动编辑

在项目的 pyproject.toml 文件中添加镜像地址：

[[tool.poetry.source]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

注意：是双中括号。

项目多镜像

[tool.poetry.source]
[[tool.poetry.source]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

[[tool.poetry.source]]
name = "custom"
url = "https://custom-mirror.example.com/simple"

验证配置

运行以下命令查看当前【全局】镜像配置：

poetry config --list

清除缓存

如果更换新的地址后，安装效果不理想。可以试试清除缓存再安装。

poetry cache clear pypi --all
poetry install

表格总结

结语

只有配置好了国内的镜像地址，才能更好的安装python项目的依赖包。更多苏南大叔的python经验文字，请点击：

• https://newsn.net/tag/python/

如果本文对您有帮助，或者节约了您的时间，欢迎打赏瓶饮料，建立下友谊关系。
本博客不欢迎：各种镜像采集行为。请尊重原创文章内容，转载请保留作者链接。