pypa/pip · error · CommandError

--no-binary / --only-binary option requires 1 argument.

Error message

--no-binary / --only-binary option requires 1 argument.

What it means

Raised as CommandError from FormatControl.handle_mutual_excludes in format_control.py:40-43. The --no-binary / --only-binary options each expect exactly one argument value; if the parsed value starts with '-' (i.e. no package name was supplied and the next token looks like a flag), pip rejects it rather than silently consuming an unrelated flag as the package list.

Solutions

Supply a package name or ':all:'/:none:' after --no-binary/--only-binary (e.g. --no-binary=:all: or --no-binary pandas).
Check shell quoting/expansion so the intended value is not dropped.
Review the command line for a missing argument before running.

Example fix

// before
pip install --no-binary mypkg
// after
pip install --no-binary=:all: mypkg

Defensive patterns

Strategy: validation

Validate before calling

// Before forwarding to pip, ensure --no-binary/--only-binary have a non-flag value:
for i, a in enumerate(argv):
    if a in ('--no-binary', '--only-binary'):
        val = argv[i+1] if i+1 < len(argv) else ''
        if not val or val.startswith('-'):
            raise SystemExit(f'{a} requires one non-flag argument')

Try / catch

from pip._internal.exceptions import CommandError
try:
    FormatControl.handle_mutual_excludes(value, target, other)
except CommandError as e:
    if 'requires 1 argument' in str(e):
        # prompt user for the missing value
        ...

Prevention

Always pass an explicit value (:all:, :none:, or a name) to --no-binary/--only-binary.
Validate argv in wrapper scripts for flag/value pairing.
Use shell arrays/quoting carefully to avoid dropping arguments.

When it happens

Trigger: Passing `--no-binary` or `--only-binary` without a following value, or with a value beginning with '-', so handle_mutual_excludes sees value.startswith('-') and raises CommandError.

Common situations: Typing `pip install --no-binary` with no argument; a shell quoting mistake that drops the package name; a script concatenating flags where the value slot is empty.

Related errors

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

Appendix: source

Thrown at src/pip/_internal/models/format_control.py:41

        self.no_binary = no_binary
        self.only_binary = only_binary

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, self.__class__):
            return NotImplemented

        if self.__slots__ != other.__slots__:
            return False

        return all(getattr(self, k) == getattr(other, k) for k in self.__slots__)

    def __repr__(self) -> str:
        return f"{self.__class__.__name__}({self.no_binary}, {self.only_binary})"

    @staticmethod
    def handle_mutual_excludes(value: str, target: set[str], other: set[str]) -> None:
        if value.startswith("-"):
            raise CommandError(
                "--no-binary / --only-binary option requires 1 argument."
            )
        new = value.split(",")
        while ":all:" in new:
            other.clear()
            target.clear()
            target.add(":all:")
            del new[: new.index(":all:") + 1]
            # Without a none, we want to discard everything as :all: covers it
            if ":none:" not in new:
                return
        for name in new:
            if name == ":none:":
                target.clear()
                continue
            name = canonicalize_name(name)
            other.discard(name)
            target.add(name)

View on GitHub (pinned to f399c37189)