pypa/pip · error · CommandError

Platform and interpreter constraints using --python-version,

Error message

Platform and interpreter constraints using --python-version, --platform, --abi, or --implementation, are not supported when selecting requirements from {filename!r}

What it means

Raised by check_dist_restriction() in cmdoptions.py:144 when platform/interpreter constraint options are used simultaneously with a pylock.toml requirements file (detected via is_valid_pylock_filename). pylock.toml files already contain fully resolved, platform-specific lock data, so applying additional platform constraints on top is unsupported and could produce incorrect results.

Source

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

            "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:
    """Function for validating build constraints options.

    :param options: The OptionParser options.
    """
    if hasattr(options, "build_constraints") and options.build_constraints:
        if not options.build_isolation:
            raise CommandError(
                "--build-constraint cannot be used with --no-build-isolation."
            )

        # Import here to avoid circular imports

View on GitHub (pinned to d7d0d0a394)

Solutions

Remove all platform/interpreter constraint options (--python-version, --platform, --abi, --implementation) when using pylock.toml.
If you need platform-specific locks, generate separate pylock.toml files per platform.
Use a standard requirements.txt file instead if you need cross-platform constraints.

Example fix

# before
pip install -r pylock.toml --platform linux_x86_64 --python-version 312

# after
pip install -r pylock.toml

Defensive patterns

Strategy: validation

Validate before calling

def validate_pylock_no_platform_opts(filenames, options):
    """Ensure pylock.toml files are not used with platform constraints."""
    import re
    pylock_pattern = re.compile(r'.*pylock.*\.toml$', re.IGNORECASE)
    has_pylock = any(pylock_pattern.match(f) for f in filenames)
    dist_set = any([options.get('python_version'), options.get('platforms'),
                    options.get('abis'), options.get('implementation')])
    return not (has_pylock and dist_set)

Try / catch

from pip._internal.exceptions import CommandError
try:
    # install with pylock + platform flags
except CommandError as e:
    if 'pylock' in str(e).lower() or 'not supported' in str(e):
        # remove platform flags and retry

Prevention

Never combine pylock.toml with platform constraint flags.
Generate separate pylock.toml files per platform.
Use standard requirements.txt if you need cross-platform constraints.

When it happens

Trigger: Calling `pip install -r pylock.toml --platform linux_x86_64 --python-version 3.12` or similar combinations where a pylock file is used as a requirements source alongside any of --python-version, --platform, --abi, or --implementation.

Common situations: Using the experimental pylock.toml support and trying to filter by platform at install time. Migrating from requirements.txt to pylock.toml but keeping old cross-platform flags in scripts.

Related errors

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