Use a prerelease version of Cookieplone

Use a prerelease version of Cookieplone#

By default, uvx cookieplone installs the latest stable release. Prerelease versions (those with an aN, bN, rcN, or .devN suffix like 2.0.0a1) are excluded from automatic resolution. This matches PEP 440 and the uv resolver defaults, and it is the right behavior for everyday use: you want the tested, stable version when you scaffold a real project.

When testing a new major version, reproducing a bug against an unreleased fix, or evaluating upcoming features, you need to opt in explicitly. This guide shows the three supported ways to do that.

Why `uvx cookieplone` skips prereleases#

uvx cookieplone is shorthand for uv tool run cookieplone. uv resolves the cookieplone requirement against PyPI the same way pip does, and PEP 440 says that prereleases are only picked when:

The requirement specifier itself is a prerelease (for example, cookieplone==2.0.0a1), or
Only prereleases satisfy the requirement (no stable release matches at all), or
The caller explicitly enables prereleases.

With a stable 1.x line published on PyPI alongside a 2.x alpha, condition (1) and (2) do not apply, so stable wins.

Option 1: Pin the exact prerelease version (recommended)#

The clearest and most reproducible option is to pin the version directly in the uvx command:

uvx cookieplone@2.0.0a1

This tells uv to create an ephemeral tool environment with exactly cookieplone==2.0.0a1, run it once, and throw the environment away. Because the version specifier is itself a prerelease, the resolver is happy to install it without any extra flags.

Confirm the running version:

uvx cookieplone@2.0.0a1 --version

You should see a line like:

Cookieplone 2.0.0a1 from ...

Option 2: Allow prereleases for one run#

If you do not want to pin a specific version (for example, because you want the latest alpha whatever its number is), pass --prerelease=allow to uvx:

uvx --prerelease=allow cookieplone

uv will resolve cookieplone against PyPI with prereleases enabled and pick the most recent version overall, stable or not. This is a per-invocation flag: the next plain uvx cookieplone reverts to the stable-only behavior.

Option 3: Install the prerelease as a persistent tool#

If you expect to run the prerelease repeatedly (for example, while working through a tutorial for the new major version), install it as a persistent uv tool:

uv tool install --prerelease=allow cookieplone

After that, cookieplone is on your PATH and every invocation uses the persistent prerelease install.

If you already installed Cookieplone this way from a stable release and want to move to a prerelease, force a reinstall so the cached stable environment is replaced:

uv tool install --reinstall --prerelease=allow cookieplone

To upgrade an existing prerelease install to the most recent prerelease on PyPI:

uv tool upgrade --prerelease=allow cookieplone

To go back to stable, reinstall without the flag:

uv tool install --reinstall cookieplone

Verify the active version#

Regardless of which option you chose, check what you are actually running:

cookieplone --version

Or, for the uvx ephemeral forms:

uvx cookieplone@2.0.0a1 --version
uvx --prerelease=allow cookieplone --version

The output includes the full version string, so you can tell 2.0.0a1 apart from 2.0.0 or 1.x at a glance.

When to use a prerelease#

You are following a tutorial or migration guide explicitly written against the upcoming major version.
You are reproducing a bug against an unreleased fix.
You are a template author validating your template against the new Cookieplone API surface before general availability.
You are evaluating new features before they land in a stable release.

For generating a real production project, prefer the stable release. Prereleases can change their CLI, config format, or filter behavior without notice, and new bugs can appear between alphas.