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 as CommandError by check_release_control_exclusive (cmdoptions.py:795) when --pre is combined with --all-releases or --only-final. The function (lines 785-798) treats --pre as sugar for --all-releases :all: when used alone; supplying both --pre and one of the newer explicit release-control flags is ambiguous, so pip rejects it. The legacy --pre flag and the new --all-releases/--only-final flags are alternative ways to express release-stage filtering.

Solutions

Use only --pre if you want pre-releases included (it is converted to --all-releases :all: internally).
Or use only --all-releases/--only-final for explicit control and drop --pre.

Example fix

# before
pip install --pre --only-final <pkg>
# after
pip install --only-final <pkg>

Defensive patterns

Strategy: validation

Validate before calling

# Normalize release-control flags to exactly one mechanism.
def normalize_release_flags(opts):
    if opts.get("pre") and (opts.get("all_releases") or opts.get("only_final")):
        raise ValueError("Use --pre OR --all-releases/--only-final, not both")
    if opts.get("pre"):
        opts["all_releases"] = ":all:"
        opts.pop("pre", None)
    return opts

Prevention

Pick one release-stage mechanism and document it in your install scripts.
When migrating off --pre, remove it rather than stacking it on the new flags.

When it happens

Trigger: `pip install --pre --all-releases <pkg>` or `pip install --pre --only-final <pkg>`.

Common situations: Migrating a script that used --pre onto the new release-control options and forgetting to remove the old flag; misunderstanding that --pre already implies accepting pre-releases.

Related errors

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

Appendix: 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 f399c37189)