python-poetry/poetry · warning · RuntimeError

Add the --all option if you want to clear all cache entries

Error message

Add the --all option if you want to clear all cache entries

What it means

Raises RuntimeError in CacheClearCommand.handle() when the user provides only a root cache name (fewer than 2 colon-separated parts) without the --all flag. Poetry requires --all to clear an entire cache root because that is a bulk, potentially destructive operation. The check at line 53-57 is `if len(parts) < 2 and not self.option('all')`.

Source

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

            parts = cache.split(":")
            root = parts[0]
        else:
            parts = []
            root = ""

        config = Config.create()
        cache_dir = config.repository_cache_directory / root

        try:
            cache_dir.relative_to(config.repository_cache_directory)
        except ValueError:
            raise ValueError(f"{root} is not a valid repository cache")

        cache = FileCache(cache_dir)

        if len(parts) < 2:
            if not self.option("all"):
                raise RuntimeError(
                    "Add the --all option if you want to clear all cache entries"
                )

            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

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Add --all: `poetry cache clear pypi --all`.
2. If you want to clear a specific entry, specify package and version: `poetry cache clear pypi:requests:2.28.0`.

Example fix

# before (error)
poetry cache clear pypi
# after
poetry cache clear pypi --all

def validate_cache_clear(cache_arg: str, all_flag: bool) -> None:
    parts = cache_arg.split(":") if cache_arg else []
    if len(parts) < 2 and not all_flag:
        raise ValueError("Add --all to clear an entire cache root")

def needs_all_flag(cache_arg: str, all_flag: bool) -> bool:
    parts = cache_arg.split(":") if cache_arg else []
    return len(parts) < 2 and not all_flag

When it happens

Trigger: Running `poetry cache clear pypi` (just a root, no package:version) without --all. The cache argument splits into 1 part, which triggers the guard.

Common situations: User wants to clear all of a specific cache and forgets --all, or expects `poetry cache clear pypi` to work without a flag.

Related errors

• Only specifying the package name is not yet supported. Add a
• 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/2c5825c142c5048a.json. Report an issue: GitHub.