Updatecli
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
namestring

“name” defines the PyPI package name.

compatible:

  • source
  • condition

remark:

  • “name” is required.

example:

  • name: requests
tokenstring

“token” defines the bearer token used to authenticate with a private registry.

compatible:

  • source
  • condition
urlstring

“url” defines the url of a PyPI compatible registry.

compatible:

  • source
  • condition

default: https://pypi.org/

versionstring

“version” defines the package version to check.

compatible:

  • condition

default: the output of the associated source.

versionfilterobject

“versionfilter” defines the version pattern and its kind, such as “pep440”, “semver” or “latest”.

compatible:

  • source

default: latest

remark:

  • yanked releases are ignored.
  • with the kind “latest”, the version is the latest release reported by the registry. The source fails when that release is yanked.
  • with a kind other than “pep440”, versions are normalised to semver and dev releases are ignored.
    kindstring

“kind” defines the versioning scheme used to select a version.

default: latest

remark:

  • accepted values are “latest”, “semver”, “regex”, “regex/semver”, “time”, “regex/time”, “lex” and “pep440”.
  • “latest” returns the last version of the list.
  • “lex” sorts the versions lexicographically and returns the last one.
  • “pep440” follows https://peps.python.org/pep-0440/

example:

  • kind: semver
    patternstring

“pattern” defines the version pattern, according to “kind”.

default:

  • latest: “latest”
  • semver and pep440: “*”
  • regex: “.*”
  • time and regex/time: “2006-01-02”

remark:

  • for “latest”, “latest” returns the last version, any other value must match a version exactly.
  • for “semver” and “regex/semver”, it is a semantic versioning constraint.
  • for “pep440”, it is a pep440 version specifier.
  • for “regex”, it is a regular expression.
  • for “time” and “regex/time”, it is a Go date layout.
  • ignored by “lex”.

example:

  • pattern: ~1.2
  • pattern: “>=1.0.0 <2.0.0”
  • pattern: ^v\d+.\d+.\d+$
    regexstring

“regex” defines the regular expression extracting the version from each entry.

remark:

  • only used by the kinds “regex/semver” and “regex/time”.
  • the value of the first capture group is used as the version.

example:

  • regex: ^v(\d+.\d+.\d+)$
    replaceallobject

“replaceall” applies a regular expression replacement to each version before filtering.

remark:

  • only used by the kinds “regex”, “regex/semver” and “regex/time”.
  • the replacement runs before “pattern” or “regex” is evaluated.

example:

replaceall:
  pattern: "_"
  replacement: "."

turns “curl-8_15_0” into “curl-8.15.0”.

    strictboolean

“strict” enforces strict semantic versioning rules when parsing versions.

default: false

remark:

  • only used by the kinds “semver” and “regex/semver”.
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 August 2, 2026
Prev
NPM
Next
Shell