pypa/pip · error · CommandError

Missing required argument (search query).

Error message

Missing required argument (search query).

What it means

Raised by SearchCommand.run() when no positional arguments are supplied. pip search requires at least one search term; with an empty args list it cannot form a query against the package index and aborts immediately.

Solutions

1. Provide a search term: `pip search <query>`.
2. If building the command dynamically, validate the query is non-empty before invoking pip.
3. Note: PyPI deprecated the XML-RPC search endpoint, so even with a query this command may fail at the network layer (see error 44).

Example fix

# before
pip search
# after
pip search requests

def run_pip_search(query: str) -> list[str]:
    if not query or not query.strip():
        raise ValueError('pip search requires a non-empty query')
    return ['pip', 'search', query]

When it happens

Trigger: Running `pip search` with no arguments, or passing only options (e.g. `pip search --index https://...`) without a query string.

Common situations: Typing `pip search` and pressing enter; scripts that build a search command but pass an empty variable as the query.

Related errors

• You must give at least one requirement to
• Key does not contain dot separated section and key. Perhaps…
• List format 'freeze' cannot be used with the --outdated…
• Needed a specific file to be modifying.
• Options --outdated and --uptodate cannot be combined.

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

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