pypa/pip · error · CommandError

You need to specify exactly one argument

Error message

You need to specify exactly one argument

What it means

Raised by `pip index versions` when the number of positional package arguments is not exactly one. get_available_package_versions at index.py:123 checks `len(args) != 1`; the versions subcommand queries one package at a time against the index.

Solutions

1. Pass exactly one package: `pip index versions <package>`.
2. Loop per package if you need versions for several.
3. Use `--json` for machine-readable single-package output.

Example fix

// before
pip index versions numpy scipy
// after
pip index versions numpy

# Validate before calling pip index versions
def validate_index_versions_args(packages):
    if not isinstance(packages, list) or len(packages) != 1:
        raise ValueError("pip index versions requires exactly one package argument")
    return True

When it happens

Trigger: Invoking `pip index versions` (zero args) or `pip index versions foo bar` (two args) — args length != 1 at index.py:124.

Common situations: User expects the command to list versions for multiple packages or forgets the package argument.

Related errors

• Can not combine '--user' and '--prefix' as they imply…
• Can not combine '--user' and '--target'
• Got unexpected number of arguments, expected
• Need exactly one file to operate upon (--user, --site…
• Please provide a pattern

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

Appendix: source

Thrown at src/pip/_internal/commands/index.py:125

        # Pass allow_yanked=False to ignore yanked versions.
        selection_prefs = SelectionPreferences(
            allow_yanked=False,
            release_control=options.release_control,
            format_control=options.format_control,
            ignore_requires_python=ignore_requires_python,
        )

        return PackageFinder.create(
            link_collector=link_collector,
            selection_prefs=selection_prefs,
            target_python=target_python,
            uploaded_prior_to=options.uploaded_prior_to,
        )

    def get_available_package_versions(self, options: Values, args: list[Any]) -> None:
        if len(args) != 1:
            raise CommandError("You need to specify exactly one argument")

        target_python = cmdoptions.make_target_python(options)
        query = args[0]

        with self._build_session(options) as session:
            finder = self._build_package_finder(
                options=options,
                session=session,
                target_python=target_python,
                ignore_requires_python=options.ignore_requires_python,
            )

            versions: Iterable[Version] = (
                candidate.version for candidate in finder.find_all_candidates(query)
            )

            if self.should_exclude_prerelease(options, canonicalize_name(query)):
                versions = (

View on GitHub (pinned to f399c37189)