mirrors/uv
1
0
Fork 0
mirror of https://github.com/astral-sh/uv.git synced 2025-08-04 02:48:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Allow users to override index cache-control headers (#14620)

Browse source 
## Summary

You can now override the cache control headers for the Simple API, file
downloads, or both:

```toml
[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
cache-control = { api = "max-age=600", files = "max-age=365000000, immutable" }
```

Closes https://github.com/astral-sh/uv/issues/10444.
This commit is contained in:
Charlie Marsh 2025-07-15 10:00:04 -04:00 • committed by GitHub
parent 9871bbdc79
commit 405ef66cef
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 323 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

37
docs/concepts/indexes.md
View file

@ -244,6 +244,43 @@ authenticate = "never"
When `authenticate` is set to `never`, uv will never search for credentials for the given index and
will error if credentials are provided directly.
### Customizing cache control headers
By default, uv will respect the cache control headers provided by the index. For example, PyPI
serves package metadata with a `max-age=600` header, thereby allowing uv to cache package metadata
for 10 minutes; and wheels and source distributions with a `max-age=365000000, immutable` header,
thereby allowing uv to cache artifacts indefinitely.
To override the cache control headers for an index, use the `cache-control` setting:
```toml
[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
cache-control = { api = "max-age=600", files = "max-age=365000000, immutable" }
```
The `cache-control` setting accepts an object with two optional keys:
- `api`: Controls caching for Simple API requests (package metadata).
- `files`: Controls caching for artifact downloads (wheels and source distributions).
The values for these keys are strings that follow the
[HTTP Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
syntax. For example, to force uv to always revalidate package metadata, set `api = "no-cache"`:
```toml
[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
cache-control = { api = "no-cache" }
```
This setting is most commonly used to override the default cache control headers for private indexes
that otherwise disable caching, often unintentionally. We typically recommend following PyPI's
approach to caching headers, i.e., setting `api = "max-age=600"` and
`files = "max-age=365000000, immutable"`.
## "Flat" indexes
By default, `[[tool.uv.index]]` entries are assumed to be PyPI-style registries that implement the