What causes "Please provide a pattern" in pypa/pip?

Provide a pattern: `pip cache remove `.

pypa/pip · error · CommandError

Please provide a pattern

Error message

Please provide a pattern

What it means

Raised by pip cache remove when no positional argument is given. remove_cache_items at cache.py:169 requires a pattern to identify what to delete; without one it cannot proceed. The CommandError is caught in CacheCommand.run and logged.

Solutions

Provide a pattern: `pip cache remove <package-or-glob>`.
Use `pip cache purge` if the intent is to clear the entire cache.
Run `pip cache list` first to see cached wheel names to target.

Example fix

// before
pip cache remove
// after
pip cache remove numpy

Defensive patterns

Strategy: validation

Validate before calling

# Validate before calling pip cache remove
def cache_remove(pattern):
    if not pattern:
        raise ValueError("pip cache remove requires a non-empty pattern")
    return subprocess.run(["pip", "cache", "remove", pattern], check=True)

Prevention

Always pass a pattern to `pip cache remove`; use `pip cache purge` to clear everything.
Inspect `pip cache list` first to choose a target pattern.

When it happens

Trigger: Invoking `pip cache remove` with no arguments — args[1:] is empty, hitting `if not args` at cache.py:169.

Common situations: User runs `pip cache remove` expecting an interactive prompt or a default, or intends to purge but types the wrong subcommand.

Related errors

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

Appendix: 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 f399c37189)