# How to Protect Against Python Supply Chain Attacks with uv


Malicious packages uploaded to PyPI are usually pulled within hours or days, either yanked or deleted outright. Holding new releases back is the cheapest defense against a [Python supply chain attack](https://pydevtools.com/handbook/explanation/what-is-a-python-supply-chain-attack.md). A [dependency cooldown](https://pydevtools.com/handbook/explanation/what-is-a-dependency-cooldown.md) tells [uv](https://pydevtools.com/handbook/reference/uv.md) to ignore packages published within a recent window, holding a compromised release out of your resolution long enough for someone else to catch it.

> [!WARNING]
> `litellm==1.107.0` is known malware, and the advisory lists no patched version. If it was installed in an environment, do not run Python or `pip` there. Rebuild the environment from a lockfile that excludes `1.107.0`, or pin `litellm==1.106.2`, then rotate every credential the affected system could read. See the [incident warning and cleanup link](https://pydevtools.com/blog/litellm-supply-chain-attack-and-securing-python-dependencies.md).

## Set a dependency cooldown

The `exclude-newer` setting accepts durations and timestamps. Security hardening wants a duration, which creates a rolling window that moves forward with the current date. [Rolling the cutoff forward with a duration](https://pydevtools.com/handbook/how-to/how-to-use-exclude-newer-for-reproducible-python-environments.md#roll-the-cutoff-forward-with-a-duration) covers every value the option takes.

### On the command line

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

This form is a one-off. uv writes the span into `uv.lock` but not into your configuration, so the next plain `uv lock` drops it, and until then `uv sync --locked` fails because the lockfile carries a setting the project no longer supplies. Use configuration for a cooldown you expect to hold.

### 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:

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

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

Use one or the other. A `uv.toml` beside `pyproject.toml` makes uv ignore `[tool.uv]` entirely, so a cooldown set there stops applying.

### In user-level configuration

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

```toml
# ~/.config/uv/uv.toml
exclude-newer = "7 days"
```
```toml
# %APPDATA%\uv\uv.toml
exclude-newer = "7 days"
```
### Enforce the cooldown in CI

Keep the cooldown in configuration rather than a pipeline-only flag, so developers and CI resolve against the same window. Then install from the lockfile:

```bash
uv sync --locked
```

`--locked` fails the job when `pyproject.toml` and `uv.lock` disagree, catching a dependency added without a fresh `uv lock`:

```console
$ uv sync --locked
Resolved 3 packages in 2ms
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.

hint: To update the lockfile, run `uv lock`.
```

A rolling window does not trip this check by itself. uv records the span in `uv.lock` rather than the timestamp it resolved to, so `uv sync --locked` and `uv lock --check` both pass on a freshly locked project.

## Let an urgent patch through the cooldown

A cooldown delays security fixes along with everything else. When the patch you need is younger than the window, exempt that one package with `exclude-newer-package` while the rest of the tree keeps its buffer:

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

Each exemption trades the buffer for speed on one package, so remove it once the window catches up. [Overriding the cutoff for one package](https://pydevtools.com/handbook/how-to/how-to-use-exclude-newer-for-reproducible-python-environments.md#override-the-cutoff-for-one-package) covers the other values the field takes.

## Choose a cooldown period

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. Both [litellm supply chain attacks](https://pydevtools.com/blog/litellm-supply-chain-attack-and-securing-python-dependencies.md) were detected and contained within hours, so a 7-day buffer would have held back all three malicious versions.

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

## Diagnose cooldown failures

### Read past the solver error

When the cooldown excludes every candidate, the solver error reads like an ordinary version conflict, and only the hint below it names `exclude-newer` as the cause. Read past the `No solution found` block before assuming the constraint is wrong. Add `-v` to the failing command to print the `Solving with exclude-newer:` line that names the value in effect.

### Check whether the index publishes upload times

The cooldown needs the `upload-time` field defined in [PEP 700](https://peps.python.org/pep-0700/), which PyPI publishes and many private indexes do not. [Exempting an index that does not publish upload times](https://pydevtools.com/handbook/how-to/how-to-use-exclude-newer-for-reproducible-python-environments.md#exempt-an-index-that-does-not-publish-upload-times) shows the failure and the fix.

## 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](https://osv.dev/) database, sourced from the OpenSSF [malicious-packages](https://github.com/ossf/malicious-packages) project. A match stops the sync before the package installs, so none of its code runs.

### In project configuration

In `pyproject.toml`, add `[tool.uv.audit]`; in `uv.toml`, add `[audit]` to enable the check for every sync in the project:

```toml
# pyproject.toml
[tool.uv.audit]
malware-check = true
```

```toml
# uv.toml
[audit]
malware-check = true
```

To query a custom advisory database instead of the default OSV endpoint, add `malware-check-url`:

```toml
# pyproject.toml
[tool.uv.audit]
malware-check = true
malware-check-url = "https://your-internal-advisory-db.example.com"
```

### With an environment variable

For CI pipelines or one-off sessions, set `UV_MALWARE_CHECK` instead:

```bash
export UV_MALWARE_CHECK=1
```
```powershell
$env:UV_MALWARE_CHECK = "1"
```
With the check enabled, uv prints an experimental-feature warning on every sync. A clean lookup adds nothing else, so an ordinary install means nothing matched:

```console
$ 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.
Installed 1 package in 4ms
 + six==1.17.0
```

A match aborts the sync before anything installs. To silence the warning for good, opt into the preview feature in configuration or set `UV_PREVIEW_FEATURES=malware-check` in CI:

```toml
# pyproject.toml
[tool.uv]
preview-features = ["malware-check"]
```

The check only blocks malware already recorded as an advisory. The cooldown covers the gap between a malicious upload and its advisory, so run both. [What the malware check blocks and what it misses](https://pydevtools.com/blog/uv-malware-check-what-it-blocks-and-what-it-misses.md) walks through the detection path.

## Layer the other defenses

A cooldown and a malware check cover the moment a new version enters the dependency tree. The remaining attack surfaces each have their own uv setting:

- **A version already pinned in `uv.lock`**: [`uv audit`](https://pydevtools.com/handbook/how-to/how-to-scan-python-dependencies-for-vulnerabilities.md) checks the locked versions against OSV, and a [lockfile](https://pydevtools.com/handbook/how-to/how-to-use-a-uv-lockfile-for-reproducible-python-environments.md) with `uv sync --locked` keeps CI from resolving anything else.
- **A tampered download**: uv verifies every artifact against the [hashes in the lockfile](https://pydevtools.com/handbook/how-to/how-to-pin-dependencies-with-hashes-in-uv.md).
- **Code that runs during installation**: `uv sync --no-build` and `uv pip install --only-binary :all:` refuse source distributions, which are the [artifacts that execute code at install time](https://pydevtools.com/handbook/explanation/why-installing-a-python-package-can-run-code.md).
- **A public package shadowing a private one**: `index-strategy` and `explicit = true` on a [private index](https://pydevtools.com/handbook/how-to/how-to-use-private-package-indexes-with-uv.md) stop uv from picking a same-named package off PyPI.
- **A package nobody has flagged yet**: [vet it before adding it](https://pydevtools.com/handbook/how-to/how-to-vet-a-python-package-before-installing-it.md).
