pypa/pip · error · CommandError

Please provide a pattern

Error message

Please provide a pattern

What it means

Raised by 'pip cache remove' (CacheCommand.remove_cache_items) when no pattern argument is supplied. Unlike list (which defaults to '*'), remove requires an explicit pattern so that users do not accidentally wipe the whole cache. The check at cache.py:169 fires when args is empty.

Source

Thrown at src/pip/_internal/commands/cache.py:170

        results = []
        for filename in files:
            wheel = os.path.basename(filename)
            size = filesystem.format_file_size(filename)
            results.append(f" - {wheel} ({size})")
        logger.info("Cache contents:\n")
        logger.info("\n".join(sorted(results)))

    def format_for_abspath(self, files: list[str]) -> None:
        if files:
            logger.info("\n".join(sorted(files)))

    def remove_cache_items(self, options: Values, args: list[str]) -> None:
        if len(args) > 1:
            raise CommandError("Too many arguments")

        if not args:
            raise CommandError("Please provide a pattern")

        files = self._find_wheels(options, args[0])

        no_matching_msg = "No matching packages"
        if args[0] == "*":
            # Only fetch http files if no specific pattern given
            files += self._find_http_files(options)
        else:
            # Add the pattern to the log message
            no_matching_msg += f' for pattern "{args[0]}"'

        if not files:
            logger.warning(no_matching_msg)

        bytes_removed = 0
        for filename in files:
            bytes_removed += os.stat(filename).st_size
            os.unlink(filename)

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Provide a package name or glob: 'pip cache remove numpy' or 'pip cache remove "numpy*"'.
2. To delete the entire cache, use 'pip cache purge'.
3. Assert your pattern variable is non-empty before invoking remove.

Example fix

// before
pip cache remove
// after
pip cache purge

if not pattern:
    raise SystemExit("'pip cache remove' needs a pattern; to wipe everything use 'pip cache purge'")

When it happens

Trigger: Running bare 'pip cache remove' with no pattern. The branch is reached right after the 'too many arguments' check passes.

Common situations: Forgetting the package name; intending 'remove everything' (use 'pip cache purge' instead); a variable that expanded to empty.

Related errors

• You must give at least one requirement to {name} (maybe you
• You must give at least one requirement to {name} (see "pip h
• Too many arguments
• Missing required argument (search query).
• You must give at least one requirement to {self.name} (see "

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/72b31565257eb345.json. Report an issue: GitHub.