Docs

PyPI

sourceconditiontarget

✔

✔

✗

Description

The pypi resource queries a PyPI-compatible registry for the versions of a Python package.

source

Returns the version matching versionfilter.

condition

Checks that version exists on the registry.

target

Not supported - a target fails with target not supported for the pypi plugin. To bump a pinned version in a file, use the "File" resource or the pyproject autodiscovery crawler.

Note
An scm attached to a condition is ignored, with a warning (the lookup always goes to the registry).

Parameters

NameTypeDescriptionRequired
namestringName defines the PyPI package name.
tokenstringToken defines the Bearer token for private registries.
urlstringURL defines the PyPI-compatible registry URL (defaults to https://pypi.org/).
versionstringVersion defines a specific package version for condition checks.
versionfilterobjectVersionFilter provides parameters to specify version pattern and its type.
    kindstringspecifies the version kind such as semver, regex, or latest
    patternstringspecifies the version pattern according the version kind for semver, it is a semver constraint for regex, it is a regex pattern for time, it is a date format
    regexstringspecifies the regex pattern, used for regex/semver and regex/time. Output of the first capture group will be used.
    replaceallobjectreplaceAll applies a regex replacement to version strings before filtering. This is useful for transforming versions (e.g., curl-8_15_0 to curl-8.15.0) before regex extraction.
    strictbooleanstrict enforce strict versioning rule. Only used for semantic versioning at this time
name

The project name as published, e.g. requests.

url

Defaults to https://pypi.org/. Point it at a private index that speaks the same JSON API.

token

Bearer token for a private registry. Keep it out of the manifest with '{{ requiredEnv "PYPI_TOKEN" }}'.

version

Condition only - the version whose existence is being checked.

Versions, PEP 440 and yanked releases

Yanked releases are always excluded, whatever the filter. A version withdrawn by its maintainer is never returned by a source, matching what pip does by default.

PEP 440 and semver disagree about how a pre-release is written (1.2.3rc1 against 1.2.3-rc1), so the resource handles them differently depending on the filter:

kind: pep440

Versions are compared as raw PEP 440 strings, untouched.

any other kind

Versions are normalised to a semver-compatible form for matching, then the original PEP 440 string is returned. So a semver filter can match 1.2.3-rc1 internally while the source still yields 1.2.3rc1, which is what a requirements file needs.

A version that cannot be normalised is skipped rather than failing the run. See the "Version Filtering" page.

Example

# updatecli.yaml
name: PyPI resource example
sources:
  requests:
    name: Get latest requests version from PyPI
    kind: pypi
    spec:
      name: requests
  flask:
    name: Get latest flask version matching >=3.0
    kind: pypi
    spec:
      name: flask
      versionfilter:
        kind: semver
        pattern: ">=3.0.0"
conditions:
  requests:
    name: Test that requests version 2.31.0 exists on PyPI
    kind: pypi
    disablesourceinput: true
    spec:
      name: requests
      version: 2.31.0
targets:
  # Targets are not supported

Links

Last updated on July 30, 2026
Prev
NPM
Next
Shell