python-poetry/poetry · error · PythonInstallationError

Failed to download and install requested version of Python.

Error message

Failed to download and install requested version of Python.

What it means

Raised as PythonInstallationError in PythonInstaller.install when pbs_installer.install() raises ValueError during the download+extract+place sequence. It signals a failure of the actual acquisition step, distinct from a version-not-found error.

Source

Thrown at src/poetry/utils/env/python/installer.py:113

                    ],
                ],
            )

        return False

    def install(self) -> None:
        try:
            # this can be broken into download, and install_file if required to make
            # use of Poetry's own mechanics for download and unpack
            pbi.install(
                self.request,
                self.installation_directory,
                version_dir=True,
                implementation=self.implementation,
                free_threaded=self.free_threaded,
            )
        except ValueError:
            raise PythonInstallationError(
                "Failed to download and install requested version of Python."
            )

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Retry on a stable network connection; clear any partial files under the installation/version directory first.
2. Verify the installation_directory is writable and has disk space.
3. Disable/adjust HTTP proxies that might be mangling the download.
4. Retry; if it persists, remove the version dir entirely and 'poetry python install <version>' again.

Example fix

// before - partial/corrupted download
PythonInstaller(request="3.12").install()  # -> PythonInstallationError

// after - clean and retry
# rm -rf <installation_dir>/python-3.12 && poetry python install 3.12

import os
from pathlib import Path

def install_dir_ready(d: Path) -> bool:
    return os.access(d, os.W_OK) and d.exists() and has_free_space(d)

from poetry.utils.env.python.installer import PythonInstallationError, PythonInstallerError

def is_python_installation_error(e: Exception) -> bool:
    return isinstance(e, PythonInstallationError) or isinstance(e, PythonInstallerError)

from poetry.utils.env.python.installer import PythonInstallationError

import time
for attempt in range(3):
    try:
        PythonInstaller(request=req).install()
        break
    except PythonInstallationError:
        clean_partial(installer.installation_directory, req)
        if attempt == 2:
            raise
        time.sleep(2 ** attempt)

When it happens

Trigger: Calling PythonInstaller(...).install() and pbs_installer.install() raises ValueError - e.g. the download was interrupted/corrupted, the archive failed integrity/extraction, or the destination path conflicts. Exact catch: installer.py:101-115.

Common situations: Network drop during download leaving a partial archive; the installation_directory is not writable or is full; a proxy/firewall corrupts the tarball; the version was withdrawn from the index between the lookup and the download; concurrent installs racing on the same version_dir.

Related errors

• No suitable standalone build found for the requested Python
• One or more installed version do not work on your system. Th
• Refusing to extract {member.name}: would write outside {dest

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