Docs

Pyproject

Description

The pyproject crawler looks recursively for all pyproject.toml files from a specific root directory. Then for each of them, it tries to update the Python dependencies declared in the [project] table.

Dependencies are read from:

  • [project.dependencies]

  • [project.optional-dependencies] (one manifest per package, per group)

Directories named .venv, pycache, .git, node_modules, .tox, .nox, and .eggs are never walked.

This crawler is enabled by default, so it can be used either automatically by running updatecli diff from a directory containing the files to update, or by providing a manifest. The automatic discovery behavior can be tuned by providing a YAML manifest with a pyproject crawler in top-level directive autodiscovery as explained in the "Autodiscovery" page.

Requirements

The crawler detects the package manager from the lock file sitting next to pyproject.toml. Only uv is supported today, via uv.lock.

The result depends on what Updatecli finds next to each pyproject.toml:

uv.lockuv command on PATHResult

present

yes

Full manifests: a pypi source and a shell target that refreshes uv.lock.

present

no

The pyproject.toml is skipped entirely, with a warning. Updatecli refuses to bump a dependency it cannot re-lock.

absent

-

Source-only manifests. Updatecli reports the latest published version but generates no target, so nothing is modified.

Tip
If a project produces no manifest at all, check that uv is installed and reachable from the environment running Updatecli.

Generated manifests

One manifest is generated per dependency, using the pypi resource as a source and a shell target:

name: 'deps(pypi): bump "requests" for "myproject" project'
sources:
  requests:
    name: 'Get latest "requests" package version'
    kind: 'pypi'
    spec:
      name: 'requests'
      versionfilter:
        kind: 'pep440'
        pattern: '>=2.28'
targets:
  requests:
    name: 'deps(pypi): bump "requests" to {{ source "requests" }}'
    kind: 'shell'
    spec:
      command: 'uv lock --upgrade-package requests=={{ source "requests" }}'
      changedif:
        kind: file/checksum
        spec:
          files:
            - "uv.lock"
      environments:
        - name: PATH
      workdir: '.'
    disablesourceinput: true

workdir points at the directory holding the pyproject.toml, so nested projects are updated in place.

Important
uv lock --upgrade-package only updates uv.lock. The version constraints declared in pyproject.toml are deliberately left untouched, so a dependency is only bumped as far as its own constraint allows. Widening a constraint such as requests>=2.28,<3 remains a manual change.

The shell target only exposes the PATH environment variable to uv. Variables such as UV_INDEX_URL, NETRC, or HOME are not inherited.

Version filtering

If no versionfilter is specified, the crawler falls back to kind: pep440 and reuses each dependency’s own constraint as the pattern, for example >=2.28 for requests>=2.28. Dependencies declared without a constraint get the pattern *.

If a versionfilter is specified, its kind is used for every generated source, and relative semver patterns are resolved against the version currently declared by each dependency. For example kind: semver with pattern: minor generates pattern: '2.x' for requests>=2.28. Explicit constraint patterns such as >=1.0.0 are used as-is.

More details on the "Version Filtering" page.

Limitations

  • Only the [project] table is read. [dependency-groups] (PEP 735), [tool.poetry], [tool.uv], and [build-system].requires are ignored, so Poetry and PDM projects yield no manifest.

  • PEP 508 direct references such as mypkg @ https://…​; or mypkg @ git+https://…​, and local path dependencies, are skipped with a warning.

  • Extras are dropped from the tracked name: black[jupyter]>=24.0 is tracked as black.

  • Environment markers are stripped, not evaluated. pywin32>=300; sys_platform == 'win32' is updated unconditionally.

Manifest

Parameters

NameTypeDescriptionRequired
ignorearrayIgnore specifies rules to exclude pyproject.toml dependencies from autodiscovery.
    packagesobjectPackages specifies the list of Python packages to match, keyed by package name. The value is a PEP 440 version specifier (e.g. “>=2.0,<3.0”) or empty to match any version.
    pathstringPath specifies a pyproject.toml path pattern. The pattern must match the full path, not just a substring. Wildcards accepted by filepath.Match are supported.
indexurlstringIndexURL specifies a custom PyPI index URL propagated to all generated source specs. It carries no credentials: authenticating against a private registry requires setting the pypi resource token field on the generated manifests.
onlyarrayOnly specifies rules to restrict autodiscovery to matching pyproject.toml dependencies.
    packagesobjectPackages specifies the list of Python packages to match, keyed by package name. The value is a PEP 440 version specifier (e.g. “>=2.0,<3.0”) or empty to match any version.
    pathstringPath specifies a pyproject.toml path pattern. The pattern must match the full path, not just a substring. Wildcards accepted by filepath.Match are supported.
rootdirstringRootDir defines the root directory used to recursively search for pyproject.toml files.
versionfilterobject

versionfilter provides parameters to specify the version pattern used when generating manifest.

If unspecified, Updatecli falls back to kind pep440 and reuses each dependency’s own constraint as the pattern, such as >=2.28 for requests>=2.28, or * when the dependency is declared without a constraint.

kind - pep440 (default) versionfilter of kind pep440 uses PEP 440 version specifiers natively pattern accepts a PEP 440 version specifier such as >=2.28, >=1.0,<3.0, or * (any)

kind - semver versionfilter of kind semver uses semantic versioning as version filtering pattern accepts one of: prerelease - Updatecli tries to identify the latest prerelease whatever it means patch - Updatecli only handles patch version update minor - Updatecli handles patch AND minor version update minoronly - Updatecli handles minor version only major - Updatecli handles patch, minor, AND major version update majoronly - Updatecli only handles major version update a version constraint such as >= 1.0.0 relative patterns such as minor are resolved against the version currently declared by each dependency, so minor generates the pattern 2.x for requests>=2.28

kind - regex versionfilter of kind regex uses regular expression as version filtering pattern accepts a valid regular expression

example:

  versionfilter:
    kind: pep440
    pattern: ">=2.28"

More examples can be found at https://www.updatecli.io/docs/core/versionfilter/

    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.
        patternstringPattern specifies the regex pattern to match for replacement
        replacementstringReplacement specifies the replacement string (supports $1, $2, etc. for captured groups)
    strictbooleanstrict enforce strict versioning rule. Only used for semantic versioning at this time
⚠ This table is generated from the Updatecli codebase and may contain inaccurate data. Feel free to report them on github.com/updatecli/updatecli
Note
Within a single only/ignore rule, path and packages must both match (AND); separate rules are combined with OR. A package version in a rule is a PEP 440 specifier evaluated against the version number extracted from the dependency’s constraint, for example 2.28 for requests>=2.28. An empty value matches any version.

Example

Basic Example

# updatecli.d/pyproject.yaml
autodiscovery:
  crawlers:
    pyproject:
      rootdir: "."
      versionfilter:
        kind: semver
        pattern: minor

Filter to Specific Packages

# updatecli.d/pyproject-only.yaml
autodiscovery:
  crawlers:
    pyproject:
      only:
        - packages:
            "requests": ""
            "flask": ""

Private PyPI Registry

# updatecli.d/pyproject-private.yaml
autodiscovery:
  crawlers:
    pyproject:
      rootdir: "."
      # Custom PyPI index URL propagated to all generated pypi source specs
      indexurl: "https://pypi.example.com/"
Note
The indexurl parameter is propagated as the url field of every generated pypi source, allowing consistent registry configuration across all discovered dependencies. It does not carry credentials: the crawler has no token parameter, so an authenticated registry requires adding the pypi resource token field to the generated manifests by hand. The uv lock target relies on `uv’s own index configuration.
Note
The alias python/uv can also be used instead of pyproject.
Last updated on July 30, 2026
Prev
Prow
Next
Rancher Fleet