Skip to content

Versioning

Once Managers have extracted dependencies, and Datasources have located available versions, then Renovate will use a "Versioning" scheme to perform sorting and filtering of results. The "versioning" is different for each package manager, because different package managers use different versioning schemes. For example, npm uses1.0.0-beta.1 and pip uses 1.0.0b1.

Why you might need to manually configure versioning

Renovate interprets versions correctly out-of-the-box most of the time. It's impossible to automatically detect all versioning schemes, so sometimes you need to tell the bot what versioning scheme it should use.

You can manually configure/override the versioning value for a particular dependency. You generally won't need to override the defaults for ecosystems which enforce a strict version scheme like npm.

Configuring or overriding the default versioning can be particularly helpful for ecosystems like Docker/Kubernetes/Helm, where versioning is barely a "convention".

General concepts behind overriding versioning

  • Although you can reconfigure versioning per-manager or per-datasource, it's unlikely that such a broad change would ever be needed
  • More commonly you would need to configure versioning for individual packages or potentially package patterns
  • The best way to do this is with packageRules, with a combination of matchManagers, matchDatasources, matchPackageNames and matchPackagePatterns. Avoid configuring versioning in a rule that also uses matchUpdateTypes, as the update types aren't known at the time the versioning is applied.

Examples of versioning overrides

Overriding Docker versioning to use a versioning specific for a package

The configuration below overrides Renovate's default docker versioning for the python Docker image and instead uses the pep440 versioning scheme to evaluate versions.

{
  "packageRules": [
    {
      "matchDatasources": ["docker"],
      "matchPackageNames": ["python"],
      "versioning": "pep440"
    }
  ]
}

Using a custom regex versioning scheme

{
  "packageRules": [
    {
      "matchPackageNames": ["foo/bar"],
      "versioning": "regex:^(?<compatibility>.*)-v?(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)?$"
    }
  ]
}

Supported Versioning

Supported values for versioning are: aws-machine-image, azure-rest-api, bazel-module, cargo, composer, conan, deb, debian, docker, git, go-mod-directive, gradle, hashicorp, helm, hermit, hex, ivy, kubernetes-api, loose, maven, nixpkgs, node, npm, nuget, pep440, perl, poetry, python, redhat, regex, rez, ruby, semver, semver-coerced, swift, ubuntu.

aws-machine-image Versioning

Identifier: aws-machine-image

Ranges/Constraints:

❌ No range support.

Description:

Renovate's AWS Machine Image versioning is a kind of hack to support Amazon Machine Images (AMI) updates.

At the moment every AMI that matches the regex ^ami-[a-z0-9]{17}$ is considered a valid "release".

azure-rest-api Versioning

Identifier: azure-rest-api

References:

Ranges/Constraints:

❌ No range support.

Description:

The Azure REST APIs use a YYYY-MM-DD version with an optional -preview suffix: https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#api-versioning

Internally at Microsoft they are using other additional suffixes: https://github.com/Azure/bicep/blob/a1d217e3bb3d049fc5c6c21b466c3a29585a6c69/src/Bicep.Core/Analyzers/Linter/ApiVersions/ApiVersionHelper.cs#L15

Bazel Module Versioning

Identifier: bazel-module

References:

Ranges/Constraints:

❌ No range support.

Cargo Versioning

Identifier: cargo

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, pin, replace

Description:

Cargo versioning uses Semantic Versioning 2.0.

Cargo supports ranges in a similar manner to npm, but not identical. The important differences are:

Use of commas

Multiple version requirements can also be separated with a comma, e.g. >= 1.2, < 1.5. We interpret this to mean AND.

No exact versions unless using equals =

In Cargo, 1.2.3 doesn't mean "exactly 1.2.3", it actually means >=1.2.3 <2.0.0. So this is like the equivalent of ^1.2.3 in npm.

Composer Versioning

Identifier: composer

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace, update-lockfile

Description:

Composer uses Semver-like versioning, but some package authors may use versions that are not completely valid, e.g. 1.2 instead of 1.2.0.

Composer supports ranges in a similar manner to npm, but not identical. The main difference is with tilde ranges.

Tilde ranges with "short" versions are different to npm. e.g.

~4 is equivalent to ^4 in npm ~4.1 is equivalent to ^4.1 in npm ~0.4 is equivalent to >=0.4 <1 in npm

Composer supports patches in the version numbers, which are considered stable. E.g., 1.2.3-p1 is recognized by npm as unstable, Renovate implements additional logic to support correct sorting and stability checks on composer patch versions syntax.

conan Versioning

Identifier: conan

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: auto, bump, widen, replace

Description:

Conan versioning supports Semantic Versioning 2.0 but some packages don't follow this specification.

Conan implements python-node-semver.

Read the Conan docs about version ranges for more information.

syntax description
5.45 Equivalent to 5.45
16.00 Equivalent to 16.00
2.8.3 Equivalent to 2.8.3
[>1.1 <2.1] Keep version within range
[2.8] Equivalent to =2.8
[~=3.0] Compatible, according to SemVer
[>1.1 \|\| 0.8] Conditions can be OR'ed
[1.2.7 \|\| >=1.2.9 <2.0.0] This range would match the versions 1.2.7, 1.2.9, and 1.4.6, but not the versions 1.2.8 or 2.0.0
[>1.1 <2.1, include_prerelease=True] Would e.g. accept 2.0.0-pre.1 as match
[~1.2.3, loose=False] Would only accept correct Semantic Versioning strings. E.g. version 1.2.3.4 would not be accepted
[~1.2.3, loose=False, include_prerelease=True] Both options can be used for the same version range

Deb version Versioning

Identifier: deb

References:

Ranges/Constraints:

❌ No range support.

Description:

Deb versioning compares versions like package managers on Debian-based Linux distributions compare packages (dpkg, apt). Deb versioning supports complicated version numbers, including alphabetical characters almost everywhere. Similar to our "loose" versioning, deb versioning is a "best effort" attempt to convert deb versions to SemVer fields like major, minor, patch.

Debian Versioning

Identifier: debian

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: pin

Description:

Debian versioning is used for Debian container images that are referenced by their major release version or a codename.

Versions to which this scheme applies are e.g. 11 and bullseye. Container image tags such as 11-slim, 11.4 or 11.4-slim, bullseye-20220822 or bullseye-backports are not compliant with the current implementation.

Docker Versioning

Identifier: docker

References:

Ranges/Constraints:

❌ No range support.

Description:

Docker images don't really have versions, instead they have "tags". Tags are often used by Docker image authors as a form of versioning.

Renovate tries to follow the most common conventions that are used to tag Docker images. In particular, Renovate treats the text after the first hyphen as a type of platform/compatibility indicator.

For example, many images have releases with the -alpine suffix. The official node Docker image has tags like 12.15.0-alpine which is not compatible with 12.15.0 or 12.15.0-stretch. Users on -alpine don't want updates to 12.16.0 or 12.16.0-stretch. Those users only want upgrades to 12.16.0-alpine and not 12.16.0 or 12.16.0-stretch.

Similarly, a user on 12.14 expects to be upgraded to 12.15 and not 12.15.0.

What type of versioning is used?

Docker image authors can use whatever tag they want, it's a "wild west". Docker tags don't always follow SemVer. This means that Renovate tries to accept and sort SemVer-like versions, but this won't always work.

You may need to help Renovate and create your own rules for some Docker images. For example:

{
  "packageRules": [
    {
      "matchDatasources": ["docker"],
      "matchPackageNames": ["badly-versioned-docker-image"],
      "versioning": "loose"
    }
  ]
}

Are ranges supported?

No. You may think a tag like 12.15 also means 12.15.x, but it's a tag of its own. The 12.15 tag may or may not point to any of the available 12.15.x tags, including 12.15.0.

Are commit hashes supported?

No, Renovate ignores Docker image tags that look like a Git commit hash.

git Versioning

Identifier: git

References:

Ranges/Constraints:

❌ No range support.

Description:

Renovate's Git versioning is a kind of hack to support Git submodule updating.

Go Modules Directive Versioning

Identifier: go-mod-directive

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, replace

Description:

This versioning is used exclusively for the go directive in go.mod files.

It ensures that a value like 1.16 is treated like ^1.16 and not ~1.16.

By default this will mean that the go directive in go.mod files won't get upgraded to any new Go version, such as 1.19. If you wish to upgrade this value every time there's a new minor Go release, configure rangeStrategy to be "bump" like so:

{
  "packageRules": [
    {
      "matchDatasources": ["golang-version"],
      "rangeStrategy": "bump"
    }
  ]
}

Gradle Versioning

Identifier: gradle

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: pin

Hashicorp Versioning

Identifier: hashicorp

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace

Description:

Hashicorp versioning syntax is used for Terraform.

It is based off Semantic Versioning 2.0 but with a subset of npm's range syntax.

helm Versioning

Identifier: helm

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace, widen

Hermit Versioning

Identifier: hermit

References:

Ranges/Constraints:

❌ No range support.

Description:

Hermit versioning is a mix of version and channel.

Version

Hermit's package version comes from the package's original Git tag. The version is an extension to SemVer, with an extra build number to accommodate package versions from OpenJDK, which has a value 15.0.1_9.

Channel

Channel could be Hermit-generated or user-defined. Channel is considered unstable version and normally won't upgrade. If you would like to get out of Channel, you could replace the Channel with a given version number and let Renovate manage it.

Hex Versioning

Identifier: hex

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace

Description:

Hex versioning syntax is used for Elixir and Erlang hex dependencies. It is based on Semantic Versioning 2.0 and supports a subset of npm's range syntax.

Ivy Versioning

Identifier: ivy

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace

Kubernetes API Versioning

Identifier: kubernetes-api

References:

Ranges/Constraints:

❌ No range support.

Loose Versioning

Identifier: loose

Ranges/Constraints:

❌ No range support.

Description:

Renovate's "loose" versioning was created for cases where no strict versioning is in place. It works like SemVer if SemVer-compliant versions are supplied, but otherwise is "best effort". Essentially "loose" versioning does its best to sort versions and ignores "unsortable" versions.

Maven Versioning

Identifier: maven

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace

Description:

Maven versioning is similar to SemVer but also very different in places. It's specified by Maven itself.

Ranges are supported using Maven's special syntax.

For development purposes, download maven-artifact JAR and run:

$ java -jar maven-artifact-*.jar 3.2.4-alpha-1 3.2.4-SNAPSHOT 3.2.4.0
Display parameters as parsed by Maven (in canonical form) and comparison result:
1. 3.2.4-alpha-1 == 3.2.4.alpha.1
   3.2.4-alpha-1 < 3.2.4-SNAPSHOT
2. 3.2.4-SNAPSHOT == 3.2.4.snapshot
   3.2.4-SNAPSHOT < 3.2.4.0
3. 3.2.4.0 == 3.2.4

Nixpkgs Versioning

Identifier: nixpkgs

References:

Ranges/Constraints:

❌ No range support.

Description:

Nixpkgs versioning is designed to be used with the nix manager.

NixOS releases follow the YY.MM pattern. There are also some prefixes and suffixes allowed. Using 22.05 as an example the allowed combination of prefixes and suffixes are:

  • release-22.05
  • nixos-22.05
  • nixos-22.05-small
  • nixos-22.05-aarch64
  • nixpkgs-22.05-darwin

Additionally, there are some floating versions:

  • nixos-unstable
  • nixos-unstable-small
  • nixpkgs-unstable

Node.js Versioning

Identifier: node

Ranges/Constraints:

❌ No range support.

Description:

Renovate's Node.js versioning is a wrapper around npm versioning. But Renovate removes any v prefixes from semantic versions when replacing.

Its primary purpose is to add Node.js LTS awareness, e.g.:

  • Odd releases are unstable
  • Even releases do not reach stability (LTS) immediately

You can not use node versioning to replace docker versioning if you are using node tags with suffixes like -alpine. This is because npm versioning treats these suffixes as implying pre-releases/instability.

npm Versioning

Identifier: npm

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace

Description:

npm versioning is the most well known/widely-used implementation of Semantic Versioning 2.0.

It's important to understand that "npm" versioning scheme is not the same as "semver" versioning. SemVer's spec does not define ranges at all - so all range/constraint syntax in npm is npm-specific and not part of the spec.

NuGet Versioning

Identifier: nuget

References:

Ranges/Constraints:

❌ No range support.

Description:

NuGet versioning matches as closely as possible to the version comparison that NuGet itself uses.

NuGet supports SemVer 2.0.0, but permits versions with differing numbers of version parts.

Ranges are not yet supported by this versioning, but they are defined in NuGet and could be supported in the future.

PEP440 Versioning

Identifier: pep440

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace

Description:

PEP 440 is defined as part of the Python project, and its versioning is independent of others such as SemVer.

Ranges are supported using the syntax defined as part of the PEP440 spec.

Perl Versioning

Identifier: perl

References:

Ranges/Constraints:

❌ No range support.

Description:

Perl versioning is based on Perl's version module.

This could be used in combination with the regex manager and the cpan datasource.

Poetry Versioning

Identifier: poetry

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace

Description:

Poetry versioning is a little like a mix of PEP440 and SemVer.

Currently Renovate's implementation is based off npm versioning. This works by parsing versions using the same patterns and similar normalization rules as Poetry, passing them to the npm versioning implementation, and then reversing the normalizations. This allows Renovate to meaningfully compare the SemVer-style versions allowed in pyproject.toml to the PEP440 representations used on PyPI. These are equivalent for major.minor.patch releases, but different for pre-, post-, and dev releases.

Python Versioning

Identifier: python

Ranges/Constraints:

❌ No range support.

Description:

Python versioning is a little like a mix of PEP440 and Poetry SemVer.

Red Hat Versioning

Identifier: redhat

Ranges/Constraints:

❌ No range support.

Description:

Red Hat versioning is used with container images that are maintained by Red Hat.

Red Hat version definitions follow this pattern:

  • the version of the main component, where major is required, but minor and patch are optional
  • optionally a hyphen followed by release information
  • the version of Red Hat's release as an integer, optionally followed by a timestamp like: 1645808164

Examples of valid Red Hat versions:

  • 1
  • 8.5
  • 7.9-628
  • 9.0.0-19.1655192132

Ranges are not supported by this versioning.

Regular Expression Versioning

Identifier: regex

Ranges/Constraints:

❌ No range support.

Description:

Regular Expression Versioning is designed to be a flexible fallback versioning approach if Renovate's other versioning schemes don't do the job.

The regex scheme makes use of Regular Express capture groups. The valid capture groups for regex versioning are:

  • major, minor, and patch: at least one of these must be provided. When determining whether a package has updates, these values will be compared in the standard semantic versioning fashion. If any of these fields are omitted, they will be treated as if they were 0 -- in this way, you can describe versioning schemes with up to three incrementing values.
  • build: this capture group can be used after you've already used the major, minor and patch capture groups and need a fourth version part. build updates are handled like patch updates.
  • revision: this capture group can be used after you've already used the build capture groups and need a fifth version part. revision updates are handled like patch updates.
  • prerelease: this value, if captured, will mark a given release as a prerelease (e.g. unstable). If this value is captured and you have configured "ignoreUnstable": true, the given release will be skipped.
  • compatibility: this value defines the "build compatibility" of a given dependency. A proposed Renovate update will never change the specified compatibility value. For example, if you are pinning to 1.2.3-linux (and linux is captured as the compatibility value), Renovate will not update you to 1.2.4-osx.

The compatibility concept was originally introduced for Docker versioning but sometimes package authors may use/misuse suffixes to mean compatibility in other versioning schemes.

Here is an example of using regex versioning to correct behavior of the guava Maven package, which misuses suffixes as compatibility indicators:

{
  "packageRules": [
    {
      "matchPackageNames": ["com.google.guava:guava"],
      "versioning": "regex:^(?<major>\\d+)(\\.(?<minor>\\d+))?(\\.(?<patch>\\d+))?(-(?<compatibility>.*))?$"
    }
  ]
}

Here is another example, this time for handling python Docker images, which use both pre-release indicators as well as version suffixes for compatibility:

{
  "packageRules": [
    {
      "matchDatasources": ["docker"],
      "matchPackageNames": ["python"],
      "versioning": "regex:^(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)(?<prerelease>[^.-]+)?(-(?<compatibility>.*))?$"
    }
  ]
}

Here is another example, this time for handling Bitnami Docker images, which use build and revision indicators as well as version suffixes for compatibility:

{
  "packageRules": [
    {
      "matchDatasources": ["docker"],
      "matchPackagePrefixes": ["bitnami/"],
      "versioning": "regex:^(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)(?:-(?<compatibility>.+)(?<build>\\d+)-r(?<revision>\\d+))?$"
    }
  ]
}

rez Versioning

Identifier: rez

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace

Description:

rez versioning was developed to support the rez Package Manager. It's based on Semantic Versioning but includes its own concept of ranges.

Use of dots

A range is expressed with dots 1.2..2 means >=1.2.x <2.0.0.

No exact versions unless using two equals ==

In rez, 1.2.3 doesn't mean "exactly 1.2.3", it actually means >= 1.2.3 <1.2.4. If you want to use an exact version use two equal characters, like this: ==1.2.3.

Use of pipes

rez uses pipes as an OR operator, 2.7..3|4 means >=2.7 <3 OR 4.x.x.

This has not been implemented yet. The current iteration of rez versioning does not support pipes yet.

Ruby Versioning

Identifier: ruby

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace

Description:

The RubyGems team urges gem developers to follow the Semantic Versioning standard for their gem’s versions, but it is not enforced.

Range syntax is similar to npm's but not identical. The main difference is the use of "pessimistic" greater than or equals: ~>

Semantic Versioning

Identifier: semver

References:

Ranges/Constraints:

❌ No range support.

Description:

Renovate's Semantic Versioning is a strict/independent implementation of Semantic Versioning 2.0. It has been developed to be used in situations where exact-only SemVer support is needed and not npm's extended semver implementation including ranges.

Ranges are not supported, in line with the specification.

Coerced Semantic Versioning Versioning

Identifier: semver-coerced

References:

Ranges/Constraints:

❌ No range support.

Description:

Renovate's Coerced Semantic Versioning is a forgiving variant of Semantic Versioning 2.0 with coercion enabled for versions.

This versioning provides a very forgiving translation of inputs in non-strict-SemVer format into strict SemVer. For example, "v1" is coerced into "1.0.0", "2.1" => "2.1.0", "~3.1" => "3.1.0", "1.1-foo" => "1.1.0". Look at the Coercion section of this page for more info on input coercion.

Since this versioning is very forgiving, it doesn't actually provide the coercion for version ranges. The range functions only accept strict SemVer as input and equivalent to those provided by the Renovate's semver versioning.

Swift Versioning

Identifier: swift

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, widen, pin, replace

Description:

Swift versioning was developed to support the Swift Package Manager. It's based on Semantic versioning but includes its own concept of ranges.

Ubuntu Versioning

Identifier: ubuntu

References:

Ranges/Constraints:

❌ No range support.

Description:

Ubuntu versioning is used for Ubuntu container images that are referenced by their release version or a codename.

Versions to which this scheme applies are e.g. 22.04 and jammy. Container image tags such as jammy-20220815 or focal-20220826 are not compliant with the current implementation.