pypa/pip · error · CommandError

--pre cannot be used with --all-releases or --only-final.

Error message

--pre cannot be used with --all-releases or --only-final.

What it means

Raised by check_release_control_exclusive() in cmdoptions.py:795 when --pre is used together with either --all-releases or --only-final. These options are mutually exclusive release-control mechanisms: --pre is a shorthand for 'include pre-releases for all packages', while --all-releases and --only-final provide more granular per-package control. Using them together is ambiguous.

Source

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

        help="Only allow final releases (no pre-releases) for a package. Can be "
        "supplied multiple times, and each time adds to the existing value. "
        'Accepts either ":all:" to disable pre-releases for all packages, '
        '":none:" to empty the set, or one or more package names with commas '
        "between them. Cannot be used with --pre.",
    )


def check_release_control_exclusive(options: Values) -> None:
    """
    Raise an error if --pre is used with --all-releases or --only-final,
    and transform --pre into --all-releases :all: if used alone.
    """
    if not hasattr(options, "pre") or not options.pre:
        return

    release_control = options.release_control
    if release_control.all_releases or release_control.only_final:
        raise CommandError("--pre cannot be used with --all-releases or --only-final.")

    # Transform --pre into --all-releases :all:
    release_control.all_releases.add(":all:")


platforms: Callable[..., Option] = partial(
    Option,
    "--platform",
    dest="platforms",
    metavar="platform",
    action="append",
    default=None,
    help=(
        "Only use wheels compatible with <platform>. Defaults to the "
        "platform of the running system. Use this option multiple times to "
        "specify multiple platforms supported by the target interpreter."
    ),
)

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Remove --pre and use --all-releases=:all: for the same effect (include all pre-releases globally).
2. Remove --all-releases or --only-final and keep --pre if you just want all pre-releases.
3. Use --all-releases=<package> for per-package pre-release inclusion without --pre.

Example fix

# before
pip install --pre --all-releases=:all: numpy

# after
pip install --all-releases=:all: numpy
# (equivalent to --pre but uses the newer API)

def validate_release_flags(options):
    """Ensure --pre is not combined with --all-releases or --only-final."""
    if not options.get('pre'):
        return True
    rc = options.get('release_control', {})
    return not (rc.get('all_releases') or rc.get('only_final'))

from pip._internal.exceptions import CommandError
try:
    # pip install with --pre and --all-releases
except CommandError as e:
    if '--pre' in str(e):
        # remove --pre or the conflicting release-control flag

When it happens

Trigger: Calling `pip install --pre --all-releases numpy` or `pip install --pre --only-final numpy` or `pip install --pre --all-releases=:all: numpy`.

Common situations: Habitually adding --pre to install commands that also use the newer --all-releases/--only-final flags. Transitioning from --pre to the more granular release control options and forgetting to remove --pre. Automation scripts that layer all release-related flags.

Related errors

• Cannot use '--only-dependencies' in combination with {confli
• When restricting platform and interpreter constraints using
• Can not use any platform or abi specific options unless inst
• Platform and interpreter constraints using --python-version,
• --build-constraint cannot be used with --no-build-isolation.

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