pypa/pip · error · CommandError

Can not use any platform or abi specific options unless inst

Error message

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

What it means

Raised by check_dist_restriction() in cmdoptions.py:133 when platform/ABI options (--python-version, --platform, --abi, --implementation) are used during a regular install (not --dry-run) without specifying a --target directory. Cross-platform installation must go to a specific target directory to avoid polluting the current environment with incompatible packages.

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 d7d0d0a394)

Solutions

1. Add `--target <directory>` to specify where cross-platform packages should be installed.
2. Alternatively, use `--dry-run` if you only want to check resolution without installing.
3. If you actually want to install for the current platform, remove the --platform/--abi/--implementation/--python-version options.

Example fix

# before
pip install --platform linux_x86_64 --python-version 312 --only-binary=:all: numpy

# after
pip install --platform linux_x86_64 --python-version 312 --only-binary=:all: --target ./vendor numpy

def validate_cross_platform_has_target(options):
    """Ensure cross-platform install has a target or dry-run."""
    dist_set = any([options.get('python_version'), options.get('platforms'),
                    options.get('abis'), options.get('implementation')])
    if not dist_set:
        return True
    return options.get('target_dir') is not None or options.get('dry_run', False)

from pip._internal.exceptions import CommandError
try:
    # cross-platform install
except CommandError as e:
    if "'--target'" in str(e):
        # add --target ./libs and retry

When it happens

Trigger: Calling `pip install --platform linux_x86_64 --python-version 3.12 --only-binary=:all: numpy` without `--target ./libs`. The check_target parameter is True for install commands.

Common situations: Building Docker images for a different architecture. Preparing a deployment directory for another platform. Forgetting that cross-platform installs cannot go into the current environment's site-packages.

Related errors

• When restricting platform and interpreter constraints using
• 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/459d3a57ed3fb4bd.json. Report an issue: GitHub.