pypa/pip · error · CommandError

Missing required argument (search query).

Error message

Missing required argument (search query).

What it means

Raised as CommandError in SearchCommand.run() at search.py:55-56 when no positional arguments are supplied. 'pip search' requires at least one search term to query the PyPI XMLRPC index; an empty query is invalid.

Source

Thrown at src/pip/_internal/commands/search.py:56

    usage = """
      %prog [options] <query>"""
    ignore_require_venv = True

    def add_options(self) -> None:
        self.cmd_opts.add_option(
            "-i",
            "--index",
            dest="index",
            metavar="URL",
            default=PyPI.pypi_url,
            help="Base URL of Python Package Index (default %default)",
        )

        self.parser.insert_option_group(0, self.cmd_opts)

    def run(self, options: Values, args: list[str]) -> int:
        if not args:
            raise CommandError("Missing required argument (search query).")
        query = args
        pypi_hits = self.search(query, options)
        hits = transform_hits(pypi_hits)

        terminal_width = None
        if sys.stdout.isatty():
            terminal_width = shutil.get_terminal_size()[0]

        print_results(hits, terminal_width=terminal_width)
        if pypi_hits:
            return SUCCESS
        return NO_MATCHES_FOUND

    def search(self, query: list[str], options: Values) -> list[dict[str, str]]:
        index_url = options.index

        session = self.get_default_session(options)

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Provide at least one search term: 'pip search <query>'.
2. If your query comes from a variable, guard the call so it only runs when the variable is non-empty.
3. Run 'pip search --help' to see usage.

Example fix

# before
pip search
# after
pip search requests

import sys
query = [a for a in sys.argv[1:] if not a.startswith('-')]
if not query:
    print('ERROR: pip search requires a non-empty query', file=sys.stderr)
    sys.exit(2)

When it happens

Trigger: Running 'pip search' with no arguments. The check 'if not args' at search.py:55 fires when the args list is empty.

Common situations: Typing 'pip search' alone expecting help; a shell alias that strips arguments; scripting that passes an empty variable as the query.

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
• Please provide a pattern
• You must give at least one requirement to {self.name} (see "
• --require-hashes and --no-require-hashes are mutually exclus

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