python-poetry/poetry · error · RuntimeError

Failed to install required Poetry plugins

Error message

Failed to install required Poetry plugins

What it means

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.

Source

Thrown at src/poetry/plugins/plugin_manager.py:296

        # force new package to be installed in the project cache instead of Poetry's env
        poetry_env.set_paths(purelib=self._path, platlib=self._path)

        self._ensure_cache_directory()

        installer = Installer(
            self._io,
            poetry_env,
            project,
            Locker(self._path / "poetry.lock", {}),
            self._poetry.pool,
            self._poetry.config,
            InstalledRepository(installed_packages),
        )
        installer.update(True)

        if installer.run() != 0:
            raise RuntimeError("Failed to install required Poetry plugins")

    def _write_config(self) -> None:
        self._ensure_cache_directory()

        document = tomlkit.document()

        for key, value in self._config.items():
            document[key] = value

        TOMLFile(self._config_file).write(data=document)

    def _ensure_cache_directory(self) -> None:
        if self._path.exists():
            return

        self._path.mkdir(parents=True, exist_ok=True)
        # only write .gitignore if path did not exist before
        self._gitignore_file.write_text("*", encoding="utf-8")

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Re-run `poetry install` (or the triggering command) with `-vvv` to see the Installer's underlying error output.
2. Check the project's declared plugins for name/version typos and that they exist on the configured source.
3. Clear the plugin cache (rm -rf .poetry/plugins) and let Poetry rebuild it.
4. Verify network/proxy access to PyPI (or your custom source) and that the Python env is writable.
5. Ensure the plugin's required Python version is compatible with the active interpreter.

Example fix

// before: plugin name typo causes resolution failure
[tool.poetry]
plugins = ["poetry-nonexistent-plugin"]

// after
[tool.poetry]
plugins = ["poetry-plugin-tweak-version-button"]

// then rebuild
$ rm -rf .poetry/plugins && poetry install

from poetry.plugins.plugin_manager import PluginManager

try:
    PluginManager.ensure_project_plugins(poetry, io)
except RuntimeError as e:
    if "Failed to install required Poetry plugins" in str(e):
        io.write_error_line("Plugin install failed; check names/versions and network.")
        # optionally continue without project plugins
        ...

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The command "{command_name}" already exists.
• Could not find a matching version of package {name}
• The Poetry plugin must be an instance of Plugin or Applicati
• Redirects are not supported. Is the URL missing a trailing s
• HTTP Error {e.response.status_code}: {e.response.reason} | {

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/eff5da56e30ead82.json. Report an issue: GitHub.