python-poetry/poetry · warning · RuntimeError

Only specifying the package name is not yet supported. Add a

Error message

Only specifying the package name is not yet supported. Add a specific version to clear

What it means

Raises RuntimeError in CacheClearCommand.handle() when the cache argument has exactly 2 colon-separated parts (root:package) but no version. Clearing by package name alone — without a specific version — is not implemented, so Poetry explicitly tells the user to add a version. The check at line 75-79 is `elif len(parts) == 2`.

Source

Thrown at src/poetry/console/commands/cache/clear.py:76

            if not cache_dir.exists():
                self.line(
                    f"No cache entries for {root}" if root else "No cache entries"
                )
                return 0

            # Calculate number of entries
            entries_count = sum(
                len(files) for _path, _dirs, files in os.walk(str(cache_dir))
            )

            delete = self.confirm(f"<question>Delete {entries_count} entries?</>", True)
            if not delete:
                return 0

            cache.flush()
        elif len(parts) == 2:
            raise RuntimeError(
                "Only specifying the package name is not yet supported. "
                "Add a specific version to clear"
            )
        elif len(parts) == 3:
            package = canonicalize_name(parts[1])
            version = parts[2]

            if not cache.has(f"{package}:{version}"):
                self.line(f"No cache entries for {package}:{version}")
                return 0

            delete = self.confirm(f"Delete cache entry {package}:{version}", True)
            if not delete:
                return 0

            cache.forget(f"{package}:{version}")
        else:
            raise ValueError("Invalid cache key")

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Append a specific version: `poetry cache clear pypi:requests:2.28.0`.
2. Use `poetry cache clear pypi --all` to clear the entire root cache if per-version targeting is too granular.

Example fix

# before (error)
poetry cache clear pypi:requests
# after
poetry cache clear pypi:requests:2.28.0
# or clear all
poetry cache clear pypi --all

def validate_cache_key(cache_arg: str) -> None:
    parts = cache_arg.split(":") if cache_arg else []
    if len(parts) == 2:
        raise ValueError(
            "Package-only clearing is not supported; add a version:"
            f" {cache_arg}:<version>"
        )

def is_full_cache_key(cache_arg: str) -> bool:
    parts = cache_arg.split(":") if cache_arg else []
    return len(parts) == 3

When it happens

Trigger: Running `poetry cache clear pypi:requests` — specifying a root and package name but no version. This hits the 2-part branch which is a not-yet-supported operation.

Common situations: User wants to clear all cached versions of a package but Poetry only supports per-version clearing. User assumes package-level clearing works.

Related errors

• Add the --all option if you want to clear all cache entries
• Invalid cache key
• You can not combine a setting value with --unset
• You can only specify one package when using the --extras opt
• Invalid config setting format: {config_setting}. Config sett

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