The exclude-newer setting tells uv to resolve dependencies as if any file uploaded after a chosen date did not exist. That keeps a resolution repeatable over time and also keeps brand new releases out of it. It filters by upload time and applies only to registry packages.
What the documentation says
The uv resolution documentation describes the option as limiting resolution to distributions uploaded before a given date. The date is checked against each file's upload time, not the release date of the version. uv treats newer distributions as nonexistent. It does not apply to Git dependencies.
The value can be a full timestamp in RFC 3339 form or a local date. Local date and time values are not allowed in persistent configuration. A project file example looks like this.
[tool.uv]
exclude-newer = "2026-09-01T00:00:00Z"
Two jobs it can do
| Goal | How exclude-newer helps |
|---|---|
| Repeat an old resolution | Fix the date to the original day and get the same candidates |
| Avoid very new releases | Set a recent date so last week's uploads are ignored |
The second use is a blunt form of a release delay. Malicious versions are often pulled soon after they appear, so ignoring the newest few days can avoid some of them. This is a risk reduction, not a guarantee, and a hostile release uploaded earlier than your date still resolves. For the wider idea, see minimum release age cooldown policies.
How it differs from a lock file
A lock file records the answer. This setting limits the question. With a lock file, nothing changes until you update. With a date cutoff, anything resolved afresh sees only what existed by that date. Use both: the lock for exact installs, the cutoff to keep the next update from grabbing the newest uploads.
A worked example
Suppose your team updates dependencies on the first of each month. On 1 October you set the cutoff to 24 September, a week earlier, and run the update. Anything published in the last seven days is ignored. If a bad release appeared on 28 September and was removed on 30 September, it never enters your resolution. If instead a real security fix landed on 28 September, you will pick it up on the next update or when you move the date.
The trade is plain: a delay buys time for the community to notice problems and costs time to receive fixes. Choose the window to match how fast you must patch.
Caveats
- A moving cutoff must be updated by hand or by automation, or you will stop receiving security fixes.
- A security fix uploaded after your date is invisible until you move the date.
- It applies to registry files, so a Git dependency is unaffected.
Quick check
Does exclude-newer use the release date or the upload date?
The upload time of each distribution file, according to the uv documentation.
Will it block a security fix?
It can, if the fix was uploaded after your cutoff date. Move the date forward when you need it.
Safeguard's zero-day discovery and dependency scanning can flag a vulnerable pinned version, and a free scan takes a manifest.
Sources
Last reviewed: 19 October 2026.
