Skip to content →

Tag: poetry

PyPI mirror support in Poetry


Back in 2018 I wrote about adding support for PyPI mirrors to pipenv. Since then, I’ve switched to using Poetry for most of my Python projects.

In 2019, I opened python-poetry/poetry#1632 to propose PyPI mirror support in Poetry. The issue languished for a bit, and several attempts at addressing it were either abandoned or rejected. There were a couple of notable complications:

  • Since Poetry does not simply wrap pip, adding support for PyPI mirrors is more involved than just setting pip’s indexes.
  • In python-poetry/poetry#1632, users expressed differing expectations for the feature. Some desired a mechanism to replace arbitrary repositories at the global scope, whereas others were strictly interested in replacing the use of
  • Poetry’s maintainers wished to avoid introducing leaky abstractions.

Concerned about the suitability of a one-size-fits-all approach to mirror support, several participants in python-poetry/poetry#4944 discussed providing support through plugins, which were introduced in Poetry 1.2. In mid-October I released poetry-plugin-pypi-mirror, which focuses specifically on supporting mirrors of


To use poetry-plugin-pypi-mirror, it must first be installed — poetry self add poetry-plugin-pypi-mirror should be sufficient for most users. Advanced plugin installation instructions are provided in Poetry’s documentation.

To use a mirror, environment variable POETRY_PYPI_MIRROR_URL should be set to the appropriate URL.

For example:

POETRY_PYPI_MIRROR_URL= poetry add pendulum


poetry add cleo # uses mirror specified in first line
poetry lock     # also uses mirror specified in first line

Alternatively, POETRY_PYPI_MIRROR_URL can be set for the user, rather than before each use of poetry.

Leave a Comment