Poetry PyPI Mirror Plugin

0.6.3 · active · verified Sat Apr 11

Poetry plugin that adds support for pypi.org mirrors and pull-through caches. It enables Poetry to substitute connections to pypi.org with connections to a mirror or pull-through cache without requiring project configuration changes. This design prevents source entries for the mirror from appearing in `poetry.lock`. The current version is 0.6.3 and it is actively maintained.

Warnings

breaking The plugin relies on Poetry's internal APIs, which are not stable and can change between Poetry releases. This may lead to unexpected behavior or breakage with newer Poetry versions. Ensure compatibility between your Poetry and plugin versions.
Fix: Always check the plugin's GitHub repository or release notes for compatibility information when upgrading Poetry or the plugin.
gotcha When configuring the mirror URL, the `POETRY_PYPI_MIRROR_URL` environment variable takes precedence over the `plugins.pypi_mirror.url` setting in `poetry`'s configuration.
Fix: Be mindful of which configuration method you use. If you experience unexpected mirror usage, check your environment variables first.
gotcha If your PyPI mirror requires authentication, you must configure credentials for the *default PyPI repository name* in Poetry, not a custom name. Use `poetry config http-basic.PyPI <username> <password>` to set credentials for the mirror.
Fix: Ensure you configure authentication for the 'PyPI' repository name within Poetry's configuration, even if it's redirecting to your custom mirror.
gotcha The plugin modifies Poetry's internal `PyPIRepository` to prevent mirror source information from being written to `poetry.lock`. This relies on internal behavior (specifically, `package._source_url` not being set). Future Poetry changes to this internal mechanism could lead to the mirror's URL appearing in `poetry.lock` unintentionally.
Fix: Periodically check your `poetry.lock` file after updates to ensure no unintended mirror source URLs are being written if this behavior is critical to your workflow.

Install

poetry self add poetry-plugin-pypi-mirror Install as Poetry plugin
pip install poetry-plugin-pypi-mirror Install via pip (if Poetry installed via pip)

Quickstart

Install the plugin using `poetry self add`. Then, configure your PyPI mirror URL either via the `POETRY_PYPI_MIRROR_URL` environment variable or by setting `plugins.pypi_mirror.url` in your Poetry configuration (global or project-specific). The environment variable takes precedence. Once configured, Poetry commands that interact with PyPI (like `poetry add` or `poetry install`) will automatically use the mirror. If authentication is required, configure it for the 'PyPI' repository using `poetry config http-basic.PyPI <username> <password>`.

# 1. Install the plugin (if not already installed)
# poetry self add poetry-plugin-pypi-mirror

# 2. Configure the PyPI mirror URL
# Option A: Environment Variable (takes precedence)
import os
import subprocess

mirror_url = os.environ.get('POETRY_PYPI_MIRROR_URL', 'https://your-private-mirror.org/simple/')

# Example using the environment variable directly with a poetry command
print(f"Using mirror: {mirror_url}")
subprocess.run([
    'poetry',
    '--version'
]) # Replace with actual poetry command using the mirror

# Option B: Poetry config (global or project-specific)
# To set globally:
# poetry config plugins.pypi_mirror.url https://your-private-mirror.org/simple/
# To set for a project (in pyproject.toml):
# [plugins.pypi_mirror]
# url = "https://your-private-mirror.org/simple/"

# 3. Add a dependency, which will use the configured mirror for PyPI
# poetry add requests

view raw JSON →