How to Use `--exclude-newer` for Reproducible Python Environments

The --exclude-newer option instructs uv to ignore any package versions published after a specified date. This creates a time-locked resolution process that ensures consistency regardless of when the installation is run.

Basic usage

Pass an RFC 3339 date or timestamp to --exclude-newer:

uv add -r requirements.txt --exclude-newer 2023-12-12

The flag also accepts a full timestamp for more precision:

uv lock --exclude-newer "2023-12-12T00:00:00Z"

Reproducing historical environments

This is particularly useful when reproducing environments for older projects. For example, if a repository was last updated in June 2023, use the flag to only resolve dependencies that were available at that time:

git clone https://github.com/example/ml-model
cd ml-model
uv add -r requirements.txt --exclude-newer 2023-06-15

Setting exclude-newer in pyproject.toml

For a persistent setting that applies to all uv operations in a project, add exclude-newer to pyproject.toml:

[tool.uv]
exclude-newer = "2023-06-15T00:00:00Z"

This ensures that anyone running uv lock or uv sync on the project uses the same time-locked resolution without needing to remember the command-line flag.

pip’s equivalent flag

pip 26.0 (January 2026) added --uploaded-prior-to, which applies the same datetime cutoff for a single command:

pip install --uploaded-prior-to 2023-06-15 -r requirements.txt

The two flags differ in scope. --exclude-newer written into pyproject.toml persists for every uv lock and uv sync in the project, so collaborators automatically get the same time-locked resolution. --uploaded-prior-to is per-command and per-invocation, so every pip call that needs the cutoff has to pass the flag. pip also does not yet write the cutoff into the generated pylock.toml.

Learn More

• uv documentation on --exclude-newer
• How to use a uv lockfile for reproducible Python environments