{"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/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/cli/cmdoptions.py#L105-L141","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add `--only-binary=:all:` to force wheel-only installation for all packages.","Alternatively, add `--no-deps` if you are manually managing dependencies.","If you need source builds for the target platform, build on the target platform itself instead of cross-installing."],"exampleFix":"# before\npip install --platform macosx_10_9_x86_64 --python-version 39 numpy\n\n# after\npip install --platform macosx_10_9_x86_64 --python-version 39 --only-binary=:all: numpy","handlingStrategy":"validation","validationCode":"def validate_cross_platform_options(options):\n    \"\"\"Ensure dist restrictions have proper guards.\"\"\"\n    dist_set = any([options.get('python_version'), options.get('platforms'),\n                    options.get('abis'), options.get('implementation')])\n    if not dist_set:\n        return True\n    binary_only = options.get('only_binary') == ':all:' and not options.get('no_binary')\n    no_deps = options.get('no_deps')\n    return binary_only or no_deps","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import CommandError\ntry:\n    # cross-platform install\nexcept CommandError as e:\n    if '--no-deps' in str(e) or '--only-binary' in str(e):\n        # add --only-binary=:all: and retry\n","preventionTips":["Always pair cross-platform flags with --only-binary=:all:.","Document required flag combinations in your build scripts.","Use --dry-run to validate option combinations before actual installs."],"tags":["cli","cross-platform","option-conflict","binary","validation"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}