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-12The 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-15Setting 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.
Tip
For most projects, a lockfile is a better solution for reproducible environments. --exclude-newer is most valuable when migrating legacy projects to uv or debugging dependency issues that appeared after a specific date.