{"id":"eff5da56e30ead82","repo":"python-poetry/poetry","slug":"failed-to-install-required-poetry-plugins","errorCode":null,"errorMessage":"Failed to install required Poetry plugins","messagePattern":"Failed to install required Poetry plugins","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/poetry/plugins/plugin_manager.py","lineNumber":296,"sourceCode":"\n        # force new package to be installed in the project cache instead of Poetry's env\n        poetry_env.set_paths(purelib=self._path, platlib=self._path)\n\n        self._ensure_cache_directory()\n\n        installer = Installer(\n            self._io,\n            poetry_env,\n            project,\n            Locker(self._path / \"poetry.lock\", {}),\n            self._poetry.pool,\n            self._poetry.config,\n            InstalledRepository(installed_packages),\n        )\n        installer.update(True)\n\n        if installer.run() != 0:\n            raise RuntimeError(\"Failed to install required Poetry plugins\")\n\n    def _write_config(self) -> None:\n        self._ensure_cache_directory()\n\n        document = tomlkit.document()\n\n        for key, value in self._config.items():\n            document[key] = value\n\n        TOMLFile(self._config_file).write(data=document)\n\n    def _ensure_cache_directory(self) -> None:\n        if self._path.exists():\n            return\n\n        self._path.mkdir(parents=True, exist_ok=True)\n        # only write .gitignore if path did not exist before\n        self._gitignore_file.write_text(\"*\", encoding=\"utf-8\")","sourceCodeStart":278,"sourceCodeEnd":314,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/plugins/plugin_manager.py#L278-L314","documentation":"Raised by ProjectPluginCache.ensure_plugins() when the Installer it runs to install project-declared plugins (under .poetry/plugins) returns a non-zero exit code. The installer resolves and installs the plugins listed in [tool.poetry.plugins] / the project plugin cache config; a failed install means the plugin environment is unusable.","triggerScenarios":"A project declares project-local plugins (the [tool.poetry] plugins mechanism backed by .poetry/plugins cache). Poetry tries to install them into the cache via the Installer; resolution or network or env errors make installer.run() return non-zero, triggering the RuntimeError.","commonSituations":"A plugin dependency version that does not resolve (conflict with Poetry's own deps); a plugin name typo; network/proxy blocking PyPI; the target Python environment is read-only or missing; a plugin requires a Python version not satisfied; corrupt .poetry/plugins cache.","solutions":["Re-run `poetry install` (or the triggering command) with `-vvv` to see the Installer's underlying error output.","Check the project's declared plugins for name/version typos and that they exist on the configured source.","Clear the plugin cache (rm -rf .poetry/plugins) and let Poetry rebuild it.","Verify network/proxy access to PyPI (or your custom source) and that the Python env is writable.","Ensure the plugin's required Python version is compatible with the active interpreter."],"exampleFix":"// before: plugin name typo causes resolution failure\n[tool.poetry]\nplugins = [\"poetry-nonexistent-plugin\"]\n\n// after\n[tool.poetry]\nplugins = [\"poetry-plugin-tweak-version-button\"]\n\n// then rebuild\n$ rm -rf .poetry/plugins && poetry install","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"from poetry.plugins.plugin_manager import PluginManager\n\ntry:\n    PluginManager.ensure_project_plugins(poetry, io)\nexcept RuntimeError as e:\n    if \"Failed to install required Poetry plugins\" in str(e):\n        io.write_error_line(\"Plugin install failed; check names/versions and network.\")\n        # optionally continue without project plugins\n        ...","preventionTips":["Validate project plugin names/versions resolve before committing [tool.poetry] plugins.","Keep the .poetry/plugins cache cleanable in CI (rm -rf before install).","Ensure CI has network access to the configured plugin source.","Pin plugin versions to avoid upstream breakage."],"tags":["plugin","install","project-plugins","network"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}