{"id":3217,"library":"poetry-plugin-pypi-mirror","title":"Poetry PyPI Mirror Plugin","description":"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.","status":"active","version":"0.6.3","language":"en","source_language":"en","source_url":"https://github.com/arcesium/poetry-plugin-pypi-mirror","tags":["poetry","pypi","mirror","plugin","package-management"],"install":[{"cmd":"poetry self add poetry-plugin-pypi-mirror","lang":"bash","label":"Install as Poetry plugin"},{"cmd":"pip install poetry-plugin-pypi-mirror","lang":"bash","label":"Install via pip (if Poetry installed via pip)"}],"dependencies":[{"reason":"This is a plugin for Poetry and relies on its internal APIs.","package":"poetry","optional":false},{"reason":"Runtime environment requirement.","package":"python","optional":false}],"imports":[],"quickstart":{"code":"# 1. Install the plugin (if not already installed)\n# poetry self add poetry-plugin-pypi-mirror\n\n# 2. Configure the PyPI mirror URL\n# Option A: Environment Variable (takes precedence)\nimport os\nimport subprocess\n\nmirror_url = os.environ.get('POETRY_PYPI_MIRROR_URL', 'https://your-private-mirror.org/simple/')\n\n# Example using the environment variable directly with a poetry command\nprint(f\"Using mirror: {mirror_url}\")\nsubprocess.run([\n    'poetry',\n    '--version'\n]) # Replace with actual poetry command using the mirror\n\n# Option B: Poetry config (global or project-specific)\n# To set globally:\n# poetry config plugins.pypi_mirror.url https://your-private-mirror.org/simple/\n# To set for a project (in pyproject.toml):\n# [plugins.pypi_mirror]\n# url = \"https://your-private-mirror.org/simple/\"\n\n# 3. Add a dependency, which will use the configured mirror for PyPI\n# poetry add requests","lang":"python","description":"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>`."},"warnings":[{"fix":"Always check the plugin's GitHub repository or release notes for compatibility information when upgrading Poetry or the plugin.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Be mindful of which configuration method you use. If you experience unexpected mirror usage, check your environment variables first.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you configure authentication for the 'PyPI' repository name within Poetry's configuration, even if it's redirecting to your custom mirror.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}