python-poetry/poetry · error · IsolatedBuildInstallError

Failed to install {requirements}.

Error message

Failed to install {requirements}.

What it means

IsolatedEnv.install (isolated_build.py) builds a Package from the PEP 508 build-system requirements, runs Poetry's Installer in the ephemeral build venv, and raises IsolatedBuildInstallError(requirements, stdout, stderr) whenever installer.run() returns non-zero. In other words: installing the build backend's own dependencies (setuptools, flit-core, hatchling, poetry-core, etc.) into the isolated environment failed. The exception carries the captured installer stdout/stderr for diagnosis.

Source

Thrown at src/poetry/utils/isolated_build.py:170

                if constraint.marker.validate(env_markers):
                    constraints_group.add_dependency(constraint)
            package.add_dependency_group(constraints_group)

        io = BufferedIO()

        installer = Installer(
            io,
            self._env,
            package,
            Locker(self._env.path.joinpath("poetry.lock"), {}),
            self._pool,
            Config.create(),
            InstalledRepository.load(self._env),
        )
        installer.update(True)

        if installer.run() != 0:
            raise IsolatedBuildInstallError(
                requirements, io.fetch_output(), io.fetch_error()
            )


@contextmanager
def isolated_builder(
    source: Path,
    distribution: DistributionType = "wheel",
    python_executable: Path | None = None,
    pool: RepositoryPool | None = None,
    *,
    build_constraints: list[Dependency] | None = None,
) -> Iterator[ProjectBuilder]:
    from build import ProjectBuilder
    from pyproject_hooks import quiet_subprocess_runner

    from poetry.factory import Factory

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Read the exception's captured stdout/stderr (it is passed into IsolatedBuildInstallError) to see the underlying installer/pip failure reason.
2. Verify sources and connectivity: `poetry source show`, and test reachability of the configured indexes.
3. Correct [build-system].requires in pyproject.toml (names, versions, markers).
4. Clear Poetry's cache (`poetry cache clear --all pypi`) and retry to rule out a stale/corrupted artifact.

Example fix

# before - build-system.requires with a typo / unreachable version
[build-system]
requires = ["poetry-cory>=1.0"]
# after
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

import tomllib
from pathlib import Path

def build_requires_look_ok(pyproject: Path) -> bool:
    data = tomllib.loads(pyproject.read_text())
    reqs = data.get('tool', {}).get('poetry', {}) \
        if False else data.get('build-system', {}).get('requires', [])
    return bool(reqs) and all(isinstance(r, str) and r.strip() for r in reqs)

from poetry.utils.isolated_build import IsolatedBuildInstallError
try:
    with isolated_builder(source) as builder:
        ...
except IsolatedBuildInstallError as e:
    # e.requirements, and the captured stdout/stderr explain the failure
    print('build deps failed:', e.requirements)
    raise

When it happens

Trigger: During `poetry build` or any dependency resolution that triggers an isolated/PEP 517 build, when [build-system].requires in a project's pyproject.toml cannot be installed in the ephemeral venv: network error, package name typo, version not present on configured sources, or conflicting constraints.

Common situations: Offline or proxy-blocked environments; private package index misconfigured or unreachable; build-system.requires pinning a version that doesn't exist; transient PyPI outage; corrupted Poetry cache.

Related errors

• Invalid build config setting '{value}'. It must be a valid J
• PEP517 build of a dependency failed
• Could not find a matching version of package {name}
• Invalid package definition.
• The following packages were not found: {', '.join(sorted(not

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