pypa/pip · error · CommandError

Can not use any platform or abi specific options unless…

Error message

Can not use any platform or abi specific options unless installing via '--target' or using '--dry-run'

What it means

Raised as CommandError by check_dist_restriction with check_target=True (cmdoptions.py:133). When dist-restriction options are set (lines 105-112) the command must either be a dry run or install into an explicit --target directory, because platform/abi-specific artifacts only make sense when you are NOT installing into the running interpreter's environment. The guard at line 132 fires when not dry_run AND a restriction is set AND no target_dir.

Solutions

1. Use `pip download` instead of `pip install` for cross-platform fetching.
2. Add `--target <dir>` so artifacts land in a separate directory rather than the live environment.
3. Add `--dry-run` to validate the resolution without writing anything.

Example fix

# before
pip install --platform manylinux2014_x86_64 --python-version 39 --only-binary=:all: numpy
# after
pip download --platform manylinux2014_x86_64 --python-version 39 --only-binary=:all: numpy

# Choose download vs install based on whether constraints are set.
def pick_command(opts):
    restricted = any(opts.get(k) for k in ("python_version", "platforms", "abis", "implementation"))
    if restricted and opts.get("command") == "install" and not (opts.get("target_dir") or opts.get("dry_run")):
        raise ValueError("Use 'pip download', or add --target/--dry-run, when cross-targeting")
    return True

When it happens

Trigger: `pip install --platform manylinux2014_x86_64 <pkg>` (install, no --target, no --dry-run), or any install using --python-version/--abi/--implementation without --target.

Common situations: Confusing `pip install` with `pip download` when doing cross-platform resolution; forgetting --target when setting up an offline bundle for another machine.

Related errors

• Platform and interpreter constraints using…
• When restricting platform and interpreter constraints using…
• --build-constraint cannot be used with --no-build-isolation.
• Cannot combine '--path' with '--user' or '--local'
• Cannot use '--only-dependencies' in combination with

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

Appendix: source

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

    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

        for filename in options.requirements:
            if pylock_utils.is_valid_pylock_filename(filename):
                raise CommandError(
                    "Platform and interpreter constraints using "
                    "--python-version, --platform, --abi, or --implementation, "
                    f"are not supported when selecting requirements from {filename!r}"
                )


def check_build_constraints(options: Values) -> None:

View on GitHub (pinned to f399c37189)