Dependency cooldown

Skip index artifacts uploaded in the last few days, so maintainers have time to catch and yank a compromised or broken release before your machine picks it up. Reach for this when you install or upgrade tools from a public index and can afford to lag the newest version.

Set it per command

--cooldown DAYS works on install, install-all, inject, upgrade, upgrade-all and run:

$ pipx install --cooldown 7 httpie

pipx translates one policy for both backends: pip receives --uploaded-prior-to P7D and uv receives --exclude-newer P7D.

Under the pip backend the cooldown also covers the shared pip that pipx installs or refreshes during the command. A new shared environment starts from the oldest pip pipx supports, then upgrades only to a release older than the cooldown; when none is, or the index publishes no upload times, pipx keeps that oldest pip. The metadata value in the table below does not apply here: only --cooldown and PIPX_COOLDOWN do, and pipx upgrade-shared ignores both.

Set it for a machine

Export PIPX_COOLDOWN so every one of those commands picks it up:

$ export PIPX_COOLDOWN=7
$ pipx install httpie
$ pipx upgrade-all

Put the export in your shell profile to make it stick across sessions. pipx has no configuration file; see Environment variables for the full list.

Which value pipx uses

Rank

Source

Notes

1

--cooldown DAYS

Wins over everything. --cooldown 0 opts one command out of a machine-wide setting.

2

PIPX_COOLDOWN

Applies to the commands listed above. Outranks whatever an earlier install recorded.

3

cooldown_days in the environment’s metadata

The value the environment’s last install recorded. See Metadata.

A locked install ignores all three: pylock.toml already pins every version. Passing --cooldown together with --lock errors, while PIPX_COOLDOWN yields and the install proceeds.

Verify it

Read back the variable and the value the environment recorded:

$ pipx environment --value PIPX_COOLDOWN
7
$ pipx list --output json | jq '.venvs.httpie.metadata.main_package.cooldown_days'
7

An invalid value stops the command before it starts:

$ PIPX_COOLDOWN=lots pipx install httpie
PIPX_COOLDOWN must be unset or a non-negative integer, got 'lots'.