ARTIFACTORY: Enabling Time-Based Package Filtering for PyPI Repositories

Introduction 

Modern Python package managers such as pip (version 26.0 and later) and uv support time-based filtering of packages using the upload-time metadata field defined in PEP 700. This allows users to install only packages uploaded before a given date, which is useful for reproducible builds, supply chain security, and minimum-age policies.

Artifactory supports this through the PyPI Simple JSON API (PEP 691 + PEP 700). This feature is not enabled by default and must be explicitly activated.


Background: PEP 691 and PEP 700
PEP 691 introduced a JSON alternative to the HTML-based Simple Repository API (PEP 503). Instead of parsing HTML, clients can request JSON-formatted package indexes using content negotiation:

Accept: application/vnd.pypi.simple.v1+json

PEP 700 extended the JSON Simple API with additional fields:

versions: list of all published versions for a project

```
size: file size in bytes
```

upload-time: ISO 8601 timestamp of when the file was uploaded

The upload-time field is the key enabler for all time-based filtering functionality.


Client Tools Using upload-time

pip 26.0+ : --uploaded-prior-to
This option filters packages to include only those uploaded before a specified datetime. It requires the repository index to provide the upload-time field in the JSON response. If the field is missing, pip fails immediately.

Syntax:

pip install <package> --uploaded-prior-to 2026-04-01T00:00:00Z


This option uses an exclusive upper bound. For example, specifying 2026-04-01 excludes packages uploaded on or after 2026-04-01 00:00:00.

uv : --exclude-newer
The uv package manager provides similar functionality, primarily for supply chain protection scenarios such as dependency cooldown periods.

Examples:

uv pip install <package> --exclude-newer "2 weeks"
uv pip install <package> --exclude-newer 2026-04-01T00:00:00Z

Configuration via uv.toml or pyproject.toml:

[tool.uv]
exclude-newer = "2 weeks"

When --exclude-newer is used with an index that does not provide upload-time, uv emits a warning and may skip those packages.


Artifactory Support

PyPI Simple JSON API

Endpoint: /api/pypi/<repo>/simple/<package>/

Trigger: Accept: application/vnd.pypi.simple.v1+json

Availability:

```
SaaS: from version 7.139.1
```
```
Self-hosted: from version 7.133.x
```

This API provides the upload-time field required by pip and uv.

Important: This feature is opt-in and must be explicitly enabled.


How to Enable

Navigate to Administration > Artifactory Settings > Package Settings

```
Under PyPI, enable Simple JSON format
```
```
Click Save
```

For self-hosted instances, the UI toggle is available starting from Artifactory 7.146. On versions earlier than 7.146, the toggle is not exposed in the UI and the feature has to be enabled via system properties.

If you are running a Self-Hosted Artifactory 7.133.x the feature can still be enabled manually by adding the following properties to $ARTIFACTORY_HOME/var/etc/artifactory/artifactory.system.properties and restarting Artifactory:

artifactory.pypi.simple.json.format.enabled=true
artifactory.pypi.local.upload.calculated.runtime.package.index=true
artifactory.pypi.simple.json.local.indexing=true

After updating the file, restart the Artifactory service for the changes to take effect.


Example JSON Response

curl -u <user>:<pass> \
 -H "Accept: application/vnd.pypi.simple.v1+json" \
 "https://<artifactory>/api/pypi/<repo>/simple/<package>/"

Example output:

{
 "filename": "requests-2.33.1.tar.gz",
 "hashes": {
   "sha256": "18817f8c57c6..."
 },
 "url": "../../packages/packages/.../requests-2.33.1.tar.gz",
 "requires-python": ">=3.10",
 "upload-time": "2026-03-30T16:09:15.531306Z",
 "yanked": false,
 "provenance": null,
 "size": 134120
}



Limitations and Considerations

Opt-in Enablement Required: The Simple JSON API is not enabled by default. Without it, clients will receive HTML responses which do not contain upload-time metadata, and time-based filtering flags will fail.

Virtual Repository Behavior: Virtual repositories only serve JSON if all included sub-repositories can provide it. If any sub-repository is restricted to HTML, the virtual repository responds with HTML to maintain consistency.

Fallback Logic: If JSON is requested but not available, Artifactory falls back to HTML. If HTML is requested but not available, nothing is returned.

Offline Availability Risk: If JSON indexing is disabled after caching indexes from a remote source, access to those indexes may be lost if the remote source is offline. Artifactory cannot fetch HTML equivalents from an offline repository.