Implement a relative cooldown in `--exclude-newer`

[potiuk]

What's the problem this feature will solve?

I think it would be great if pip implements a "cooldown" feature. This has been recently widely discussed in the security community after the npm being targetted by the Shai-Hulud 2 malware, that cooldowns would be a great protection for - especially - open-source projects and libraries that do not necessary need to get the latest packages immediately.

Cooldown periods will give time to registry maintainers (both public PyPI and other registries) to perform necessary scans, security researchers reviews, AI tools, running sandboxed tests by security-focused 3rd-parties on new versions of packages release and increase the chance that malware will be detected before it is installed.

This article from @woodruffw https://blog.yossarian.net/2025/11/21/We-should-all-be-using-dependency-cooldowns describes the cooldown effects pretty well, and calls for everyone to use cooldowns.

It's easy with dependabot and renovate on CI, however there is also another vector of attack - locak workstations of developers where the install packages, and it would be great to have confguration and option to have cooldown period applied by default on those workstations.

Of course there is the --exclude-newer but it only has support for specifying the absolute date, not relative one. Of course you could do all the bash or zsh magic to calculate it, but that's not really an option if you would like to configure a default cooldown period.

UV already has a PR in progress about it https://github.com/astral-sh/uv/pull/16814 after very deep discussion about it - and it aims to allow relative specification for the --exclude-newer, which I think is a very good idea.

It would be great to have such relative --exclude-newer in pip - both as command line and configurable default.

Describe the solution you'd like

The --exclude-newer could accept other values than absolute timestamp - specifically relative time specification like '1 day, 1 week, 30 days`.

Alternative Solutions

Telling people to calculate the date and pass it to --exclude-newer in the absolute timestamp form. Unfortunately that does not achieve easily the "default behaviour" of specific cooldown period like 5 days.

Additional context

https://blog.yossarian.net/2025/11/21/We-should-all-be-using-dependency-cooldowns

Code of Conduct

• [x] I agree to follow the PSF Code of Conduct.

[potiuk]

Ok. It looks like it's somewhat related to https://github.com/pypa/pip/pull/13625 - have not found it, also the old https://github.com/pypa/pip/issues/6257 that described the ask, but the currrent PR does not have the relative specs which is a key here, and it likely might be something to add add as part of it.

[notatallshaw]

My main focus at the moment is to get https://github.com/pypa/pip/pull/13625 out for pip 26.0, and then as you say users will be able to manually precompute a value and pass it to pip, e.g.

--uploaded-prior-to $(date --utc -d "7 days ago" "+%Y-%m-%dT%H:%M:%SZ")

As I mentioned in https://github.com/jazzband/pip-tools/issues/2288#issuecomment-3592089085 I think there are a lot of UX questions that need to be answered for a hypothetical --cooldown option. The main use case of --uploaded-prior-to is reproducibility where as the main use case of a --cooldown option would be about security. I would have these following questions for any PR:

• How should --cooldown be parsed? Do they have to be English language words? Would we need to vendor a new library to do that?
• If both --uploaded-prior-to and --cooldown flag are passed what should happen?
• Should --cooldown accept indexes which don't provide upload-time metadata or error out immediately like --uploaded-prior-to?
• Would users require a way to exclude packages from --cooldown for critical bug fixes? If so, should that exclusion apply to --uploaded-prior-to or not?

These questions don't have to all be answered now, in fact I'm rather inclined to take a "wait and see" approach to how other Python packaging tools, like uv, end up implementing these options and what issues they face with users, especially once there is a workaround for users.