How to Protect Against Python Supply Chain Attacks with uv

Malicious packages uploaded to PyPI are usually caught and yanked within hours or days. A dependency cooldown tells uv to ignore packages published within a recent window, so compromised versions get removed before they ever reach your environment.

Set a dependency cooldown

The exclude-newer setting accepts durations and timestamps. For security hardening, durations are the right choice because they create a rolling window that moves forward with the current date.

On the command line

uv lock --exclude-newer "7 days"
uv sync --exclude-newer "7 days"

In project configuration

Add the setting to pyproject.toml or uv.toml so it applies to every uv lock and uv sync in the project:

# pyproject.toml
[tool.uv]
exclude-newer = "7 days"

# uv.toml
exclude-newer = "7 days"

In user-level configuration

Apply the cooldown to all projects on a machine by adding it to the user-level uv.toml:

# ~/.config/uv/uv.toml
exclude-newer = "7 days"

# %APPDATA%\uv\uv.toml
exclude-newer = "7 days"

Accepted duration formats

Durations are resolved to a fixed number of seconds assuming 24-hour days (DST is ignored). Calendar units like months and years are not allowed.

Let an urgent patch through the cooldown

When a security fix lands inside the cooldown window, exclude-newer-package overrides the global setting for a single package. Set it to false to exempt that package entirely, or to a timestamp or duration to give it a different window:

[tool.uv]
exclude-newer = "7 days"
exclude-newer-package = { my-package = false }   # install my-package regardless of age

uv lock --exclude-newer "7 days" --exclude-newer-package my-package=false

Per-package values take precedence over the global cooldown, so the rest of the dependency tree keeps its seven-day buffer while the exempted package resolves to its newest release.

Choose a cooldown period

The right window depends on how fast a project needs new releases versus how much risk it can tolerate.

7 days is a practical default. Most malicious uploads are detected within this window, and most projects can wait a week for new dependency versions. The litellm supply chain attack in March 2026 was discovered and yanked within hours, so a 7-day buffer would have been more than enough.

30 days suits production deployments and internal tooling where stability matters more than access to recent releases.

Caveats

Silent exclusion. When exclude-newer filters out a package version, uv does not mention it in error messages. If resolution fails because the only matching version was published too recently, the error will say no compatible version exists. Keep this in mind when debugging resolution failures.

Index compatibility. The cooldown relies on the upload-time field defined in PEP 700. PyPI supports this field. Custom or private indexes may not, in which case exclude-newer has no effect for packages hosted there.

Block known malware at install time

A cooldown buys time for malicious uploads to be detected. uv’s malware check acts on the detections themselves: with the check enabled, every command that syncs the environment (uv add, uv sync, and others) looks up the locked packages against the MAL advisories in the OSV database, sourced from the OpenSSF malicious-packages project. If a locked package matches an advisory, uv stops the sync before the package is installed, so none of its code runs.

Enable the check with the UV_MALWARE_CHECK environment variable:

export UV_MALWARE_CHECK=1

$env:UV_MALWARE_CHECK = "1"

With the variable set, each sync reports the lookup:

$ uv sync
Resolved 2 packages in 2ms
warning: Malware checks are experimental and may change without warning. Pass `--preview-features malware-check` to disable this warning.
Checked 1 package in 0.39ms

The check only blocks malware that has already been identified and recorded as an advisory. The gap between a malicious upload and its advisory is the window the cooldown covers, so run both.

Learn more

• uv: A Complete Guide covers what uv does, how fast it is, the core workflows, and recent releases.
• --exclude-newer for reproducible environments
• How to Scan Python Dependencies for Vulnerabilities covers uv audit, the after-the-fact companion to these install-time defenses.
• LiteLLM supply chain attack and securing Python dependencies
• uv documentation on dependency cooldowns
• Vulnerability and malware checks in uv is Astral’s announcement of the malware check and uv audit.