Registry / devops / poetry-plugin-pypi-mirror

poetry-plugin-pypi-mirror

library0.6.3pypypiunverified

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.

devops

poetry self add poetry-plugin-pypi-mirror

github ↗package ↗

INSTALL

IMPORT

SIG · POETRY-PLUGIN-PYPI

poetry-plugin-pypi-mirror

devopspythonv0.6.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

Debug

Known issues

breakingThe 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.

affects: All versions

gotchaWhen 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.

affects: All versions

gotchaIf 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.

affects: All versions

gotchaThe 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.

affects: All versions

Errors

Common errors & fixes

The following packages are already present in the pyproject.toml and will be skipped: - poetry-plugin-pypi-mirror

You are attempting to install the `poetry-plugin-pypi-mirror` plugin when it is already installed or listed in Poetry's global or project configuration.

fix

If you intended to update the plugin, use `poetry self update poetry-plugin-pypi-mirror` or `poetry self add poetry-plugin-pypi-mirror@latest`.

ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE.

When using a PyPI mirror, Poetry's internal hash checking of downloaded packages can fail if the mirror serves a different file (even if functionally identical) than expected, or if the Poetry installer is run in an isolated mode that prevents it from respecting mirror configurations.

fix

Ensure your mirror is correctly configured and accessible. The `poetry-plugin-pypi-mirror` is designed to handle this transparently for project dependencies when configured via `POETRY_PYPI_MIRROR_URL` or `plugins.pypi_mirror.url`. If this error occurs during Poetry's own installation, workarounds might involve temporarily disabling hash checks or ensuring `pip.conf` is respected during the installation script.

ERROR: No matching distribution found for <package_name>

Poetry cannot find the requested package in the configured PyPI mirror or primary index. This typically indicates an incorrect mirror URL, the package not being available on the mirror, or a connectivity issue to the mirror.

fix

Verify that the `POETRY_PYPI_MIRROR_URL` environment variable or the `plugins.pypi_mirror.url` setting in your Poetry configuration (`poetry config --list`) is correct and points to a valid and accessible PEP 503-compatible mirror. Also, confirm that the desired package is actually available on the configured mirror.

WARNING: Retrying (Retry(total=X, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(...)'

Poetry, or the underlying `pip` which Poetry uses, is unable to establish a secure connection to the PyPI mirror due to SSL certificate issues, firewall restrictions, or general network problems.

fix

Check network connectivity to your mirror URL. Ensure that corporate proxies or firewalls are not interfering with SSL connections. You may need to configure proxy settings for Poetry (`poetry config http-proxy` and `poetry config https-proxy`) or ensure the necessary CA certificates are trusted in your environment.

Upgrade

Version history

0.6.3latest on PyPI · released Jan 19, 2026

Audit

Dependencies

poetryrequiredThis is a plugin for Poetry and relies on its internal APIs.

pythonrequiredRuntime environment requirement.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/arcesium/poetry-plugin-pypi-mirror ↗

packagehttps://pypi.org/project/poetry-plugin-pypi-mirror/ ↗