pypa/pip · error · CommandError

When restricting platform and interpreter constraints using

Error message

When restricting platform and interpreter constraints using --python-version, --platform, --abi, or --implementation, either --no-deps must be set, or --only-binary=:all: must be set and --no-binary must not be set (or must be set to :none:).

What it means

Raised by check_dist_restriction() in cmdoptions.py:123 when platform/interpreter constraint options (--python-version, --platform, --abi, --implementation) are used without either --no-deps or --only-binary=:all:. This is because cross-platform installs that allow source distributions could build wheels incompatible with the target platform, creating silently broken installations.

Source

Thrown at src/pip/_internal/cli/cmdoptions.py:123

    dist_restriction_set = any(
        [
            options.python_version,
            options.platforms,
            options.abis,
            options.implementation,
        ]
    )

    binary_only = FormatControl(set(), {":all:"})
    sdist_dependencies_allowed = (
        options.format_control != binary_only and not options.ignore_dependencies
    )

    # Installations or downloads using dist restrictions must not combine
    # source distributions and dist-specific wheels, as they are not
    # guaranteed to be locally compatible.
    if dist_restriction_set and sdist_dependencies_allowed:
        raise CommandError(
            "When restricting platform and interpreter constraints using "
            "--python-version, --platform, --abi, or --implementation, "
            "either --no-deps must be set, or --only-binary=:all: must be "
            "set and --no-binary must not be set (or must be set to "
            ":none:)."
        )

    if check_target:
        if not options.dry_run and dist_restriction_set and not options.target_dir:
            raise CommandError(
                "Can not use any platform or abi specific options unless "
                "installing via '--target' or using '--dry-run'"
            )

    if dist_restriction_set:
        # Lazy import to keep CLI startup fast
        from pip._internal.utils import pylock as pylock_utils

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Add `--only-binary=:all:` to force wheel-only installation for all packages.
2. Alternatively, add `--no-deps` if you are manually managing dependencies.
3. If you need source builds for the target platform, build on the target platform itself instead of cross-installing.

Example fix

# before
pip install --platform macosx_10_9_x86_64 --python-version 39 numpy

# after
pip install --platform macosx_10_9_x86_64 --python-version 39 --only-binary=:all: numpy

def validate_cross_platform_options(options):
    """Ensure dist restrictions have proper guards."""
    dist_set = any([options.get('python_version'), options.get('platforms'),
                    options.get('abis'), options.get('implementation')])
    if not dist_set:
        return True
    binary_only = options.get('only_binary') == ':all:' and not options.get('no_binary')
    no_deps = options.get('no_deps')
    return binary_only or no_deps

from pip._internal.exceptions import CommandError
try:
    # cross-platform install
except CommandError as e:
    if '--no-deps' in str(e) or '--only-binary' in str(e):
        # add --only-binary=:all: and retry

When it happens

Trigger: Calling `pip install --platform macosx_10_9_x86_64 --python-version 3.12 <pkg>` without also specifying --no-deps or --only-binary=:all:. Or using --abi/--implementation constraints without the required binary-only or no-deps guard.

Common situations: Cross-compiling or installing for a different platform (common in embedded/IoT, Docker multi-arch builds, CI for multiple OS targets). Forgetting that cross-platform mode requires all-binary to avoid building incompatible sdists.

Related errors

• Can not use any platform or abi specific options unless inst
• Platform and interpreter constraints using --python-version,
• Cannot use '--only-dependencies' in combination with {confli
• --build-constraint cannot be used with --no-build-isolation.
• --pre cannot be used with --all-releases or --only-final.

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