python-poetry/poetry · error · PoetryRuntimeError

Downloaded distributions for <b>{package.pretty_name} ({pack

Error message

Downloaded distributions for <b>{package.pretty_name} ({package.pretty_version})</> did not match any known checksums in your lock file.

What it means

Raised by Chooser._get_links at src/poetry/installation/chooser.py:242-264 as PoetryRuntimeError when the repository returned links for the package but, after filtering against locked hashes, zero links remained. The message lists causes (corrupt cache, network errors) and the skipped vs known hashes. This is a checksum/integrity mismatch between the repository and poetry.lock.

Source

Thrown at src/poetry/installation/chooser.py:264

            messages = [
                ConsoleMessage(
                    "<options=bold>Causes:</>\n"
                    "  - invalid or corrupt cache either during locking or installation\n"
                    "  - network interruptions or errors causing corrupted downloads\n\n"
                    "<b>Solutions:</>\n"
                    "  1. Try running your command again using the <c1>--no-cache</> global option enabled.\n"
                    "  2. Try regenerating your lock file using (<c1>poetry lock --no-cache --regenerate</>).\n\n"
                    "If any of those solutions worked, you will have to clear your caches using (<c1>poetry cache clear --all CACHE_NAME</>)."
                ),
                ConsoleMessage(
                    f"Poetry retrieved the following links:\n"
                    f"{link_hashes}\n\n"
                    f"The lockfile contained only the following hashes:\n"
                    f"{known_hashes}",
                    debug=True,
                ),
            ]
            raise PoetryRuntimeError(reason, messages)

        return selected_links

    def _sort_key(
        self, package: Package, link: Link
    ) -> tuple[int, int, int, Version, tuple[Any, ...], int]:
        """
        Function to pass as the `key` argument to a call to sorted() to sort
        InstallationCandidates by preference.
        Returns a tuple such that tuples sorting as greater using Python's
        default comparison operator are more preferred.
        The preference is as follows:
        First and foremost, candidates with allowed (matching) hashes are
        always preferred over candidates without matching hashes. This is
        because e.g. if the only candidate with an allowed hash is yanked,
        we still want to use that candidate.
        Second, excepting hash considerations, candidates that have been
        yanked (in the sense of PEP 592) are always less preferred than

View on GitHub (pinned to 92b74dcfe3)

Solutions

Run `poetry lock --no-cache --regenerate` to rebuild the lock file from current repository hashes.
Retry the install with `--no-cache` to bypass a poisoned cache: `poetry install --no-cache`.
Clear the offending cache: `poetry cache clear --all <CACHE_NAME>` (list with `poetry cache list`).
Verify the configured repository still serves the exact files (a mirror change is a common root cause).

Example fix

# before
$ poetry install
RuntimeError: ... did not match any known checksums ...

# after
$ poetry lock --no-cache --regenerate
$ poetry install

Defensive patterns

Strategy: retry

Try / catch

from poetry.installation.exceptions import PoetryRuntimeError

try:
    installer.run()
except PoetryRuntimeError as e:
    if 'did not match any known checksums' in str(e):
        # regenerate and retry once
        run('poetry', 'lock', '--no-cache', '--regenerate', check=True)
        installer.run()
    else:
        raise

Prevention

Keep poetry.lock committed and in sync with pyproject.toml.
Periodically clear caches; pin index URLs so artifacts don't drift.
Avoid mirroring indexes that rewrite artifacts without stable hashes.

When it happens

Trigger: Install/update with a populated poetry.lock: for every link found in the repo, none of its hashes (or computed sha256 for HTTPRepository) appear in the lock file's package.files hashes. Happens after a mirror was republished, a cache served a stale/ corrupt file, or the lock file is from an unrelated set of artifacts.

Common situations: Corporate PyPI mirror desynced from upstream; poetry's HTTP cache poisoned by an interrupted download; a lock file committed from a different index than the one currently configured; package yanked-and-reuploaded under the same version.

Related errors

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