{"record":{"id":"bcc58b12d6333bf4","repo":"pypa/pip","slug":"when-restricting-platform-and-interpreter-constrai","errorCode":null,"errorMessage":"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:).","messagePattern":"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:\\)\\.","errorType":"exception","errorClass":"CommandError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/cli/cmdoptions.py","lineNumber":123,"sourceCode":"    dist_restriction_set = any(\n        [\n            options.python_version,\n            options.platforms,\n            options.abis,\n            options.implementation,\n        ]\n    )\n\n    binary_only = FormatControl(set(), {\":all:\"})\n    sdist_dependencies_allowed = (\n        options.format_control != binary_only and not options.ignore_dependencies\n    )\n\n    # Installations or downloads using dist restrictions must not combine\n    # source distributions and dist-specific wheels, as they are not\n    # guaranteed to be locally compatible.\n    if dist_restriction_set and sdist_dependencies_allowed:\n        raise CommandError(\n            \"When restricting platform and interpreter constraints using \"\n            \"--python-version, --platform, --abi, or --implementation, \"\n            \"either --no-deps must be set, or --only-binary=:all: must be \"\n            \"set and --no-binary must not be set (or must be set to \"\n            \":none:).\"\n        )\n\n    if check_target:\n        if not options.dry_run and dist_restriction_set and not options.target_dir:\n            raise CommandError(\n                \"Can not use any platform or abi specific options unless \"\n                \"installing via '--target' or using '--dry-run'\"\n            )\n\n    if dist_restriction_set:\n        # Lazy import to keep CLI startup fast\n        from pip._internal.utils import pylock as pylock_utils\n","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/cli/cmdoptions.py#L105-L141","documentation":"Raised as CommandError by check_dist_restriction (cmdoptions.py:123) when platform/interpreter constraint options (--python-version, --platform, --abi, --implementation) are set together with source-distribution dependencies allowed. The guard at lines 114-122 computes sdist_dependencies_allowed as format_control != only-binary:all: OR not --no-deps; combining cross-platform targeting with sdists is unsafe because source builds run against the host interpreter, not the constrained target, so the resulting artifacts are not guaranteed to be compatible.","triggerScenarios":"`pip download --platform manylinux2014_x86_64 --python-version 39 --abi cp39 <pkg>` without --only-binary=:all: or --no-deps; mixing --implementation with any package whose deps might need building.","commonSituations":"Building a wheel cache for a different platform (common in lock-file generation and air-gapped environments) and forgetting to force binary-only resolution; upgrading a resolver workflow that previously used --no-deps but dropped it.","solutions":["Add `--only-binary=:all:` (and ensure --no-binary is unset or `:none:`) so only prebuilt wheels for the target are selected.","Alternatively add `--no-deps` to skip dependency resolution entirely (you then handle deps separately).","Verify the package actually publishes wheels for your target platform/abi; if only sdists exist, cross-targeting is unsupported for that package."],"exampleFix":"# before\npip download --platform manylinux2014_x86_64 --python-version 39 --abi cp39 numpy\n# after\npip download --platform manylinux2014_x86_64 --python-version 39 --abi cp39 --only-binary=:all: numpy","handlingStrategy":"validation","validationCode":"# Enforce the cross-target rule before invoking pip.\ndef validate_cross_target(opts):\n    restricted = any(opts.get(k) for k in (\"python_version\", \"platforms\", \"abis\", \"implementation\"))\n    binary_all = opts.get(\"only_binary\") == \":all:\" and not opts.get(\"no_binary\")\n    if restricted and not (opts.get(\"no_deps\") or binary_all):\n        raise ValueError(\"Add --only-binary=:all: or --no-deps when using platform/abi constraints\")\n    return True","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair cross-platform flags with --only-binary=:all: in lock-file/bundle workflows.","Confirm wheels exist for the target platform before attempting cross-resolution."],"tags":["cli-options","platform","abi","binary","cross-target","command-error"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}