TheRock package versioning

We build and distribute packages for a variety of projects across multiple packaging systems, release channels, and operating systems.

This document describes the version schemes we use for those packages.

Table of contents:

• Overview
  • Constraints and design guidelines
  • Distribution channels (dev, nightly, release)
• Release branch metadata
• Python package versions
• Native Linux package versions
• Native Windows package versions

Overview

Generally we use semantic versioning (SemVer) for most projects, e.g. X.Y.Z where

• X is the "major version"
• Y is the "minor version"
• Z is the "patch version"

The version.json file at the root of TheRock defines the base version used for packages:

{
  "rocm-version": "10.1.0"
}

set(HIPBLASLT_PROJECT_VERSION "1.4.1" CACHE STRING "Semantic version string.")

Constraints and design guidelines

We are limited by what each packaging system accepts as valid versions.

For Python packages see:

• https://packaging.python.org/en/latest/discussions/versioning/
• https://packaging.python.org/en/latest/specifications/version-specifiers/

For Debain packages see:

• https://www.debian.org/doc/debian-policy/ch-controlfields.html#version

For Fedora packages see:

• https://docs.fedoraproject.org/en-US/packaging-guidelines/Versioning/

Distribution channels (dev, nightly, release)

Most users are expected to use stable releases, but several other distribution channels are also available and may be of interest to project developers, users who want early previews of upcoming releases, and QA/test team members.

Each distribution channel has an aggregate Python index that can be passed to package managers like pip (see RELEASES.md - Installing multi-arch Python packages for details). For example:

pip install --index-url=https://nightly.repo.amd.com/rocm/whl-next/ rocm
pip install --index-url=https://dev.repo.amd.com/rocm/whl-next/ rocm

The new layout starts with ROCm 10.1 nightlies and ROCm 10.0 stable releases. Earlier releases remain in the legacy multi-arch release locations.

With the exception of "dev releases", each distribution channel only contains release artifacts of the matching release type. The "dev releases" channel can contain any type of release.

Release branch metadata

The version.json file also contains a generic release-metadata object hosting fields that release types can interpret as needed. These fields should be empty on the base branch and may be populated by commits on release branches:

{
  "rocm-version": "10.1.0",
  "release-metadata": {
    // Empty on the base branch.
    "base-date": ""
    // A BKC release branch could set base-date to 20260811 for a package
    // version like 10.1.0a20260811+bkc.20260813 where
    //   * 20260811 is fixed to when the release branch forked from mainline
    //   * 20260813 is the current date
  }
}

Python package versions

Python package versions are handled by scripts:

• build_tools/compute_rocm_package_version.py
  • build_tools/tests/compute_rocm_package_version_test.py

The script produces these versions for each release type:

Post releases

A post release is a follow-up release of an existing package version, written in canonical form with a .postN segment. PEP 440 orders it after its base version and before the next patch: 7.14.0 < 7.14.0.post1 < 7.14.1. TheRock's scripts do not generate these versions, but we may create one manually in exceptional cases to patch an individual Python package. See the official Python packaging guidance for what qualifies as a post release.

Version comparisons in TheRock scripts and published packages should tolerate versions that differ only by a post-release segment. For example, 7.14.0 and 7.14.0.post1 should be compatible, while 7.14.0 and 7.14.1 should not. This lets us patch one package without republishing the entire package set.

BKC versions

For nightly-bkc, BASEDATE comes from release-metadata.base-date in version.json and identifies the regular nightly used to create the BKC branch. The date in the bkc.YYYYMMDD local version identifier is the BKC build date. This makes a BKC build sort newer than its base nightly but older than the next regular nightly:

10.1.0a20260811 < 10.1.0a20260811+bkc.20260814 < 10.1.0a20260812

External Python package versions

When we build external projects like PyTorch we sometimes extend the base package version with our own local version identifier.

For example, for torch version 2.9.0 built with ROCm version 7.10.0 we generate a composite torch version 2.9.0+rocm7.10.0. See this table for more possible version combinations:

These local version identifiers are specially constructed such that the expected version sorting of stable > nightly > dev is preserved. Note that per the "Local version identifiers" specification, comparison and ordering of local version identifiers goes segment by segment with special rules different from the rules used for base versions. This ordering can be tested like so:

>>> from packaging.version import Version
>>> stable = Version("2.9.0+rocm7.10.0")
>>> nightly = Version("2.9.0+rocm7.10.0a20251124")
>>> dev = Version("2.9.0+devrocm7.10.0.dev0-efed3c")
>>> stable > nightly
True
>>> nightly > dev
True

>>> from packaging.version import Version
>>> Version("2.12.0+rocm10.0") > Version("2.12.0+rocm7.0")
False

PyTorch versions

PyTorch packages versions are handled via scripts:

• build_tools/github_actions/determine_version.py (this generates e.g. --version-suffix +rocm7.10.0)
  • build_tools/github_actions/tests/determine_version_test.py
• external-builds/pytorch/build_prod_wheels.py (this appends the version suffix to each build version)
• build_tools/github_actions/write_torch_versions.py (this finds the versions in built packages)
• build_tools/github_actions/generate_pytorch_source_manifest.py (this computes expected PyTorch ecosystem package versions and records them with pinned source commits for checkout/build jobs)
• external-builds/pytorch/checkout_from_manifest.py (this checks out the exact source commits recorded in the manifest)

The scripts produce these versions for each distribution channel:

For manually dispatched dev PyTorch builds (build_prod_wheels.py --release-type dev), each wheel version is additionally tagged with its own 8-character source commit in the PEP 440 local version segment, e.g. 2.12.0a0+git1a2b3c4d.rocm7.10.0. This applies to the torch, torchaudio, and torchvision wheels, so each records exactly which source commit produced it.

JAX versions

JAX packages versions are handled via scripts:

• build_tools/github_actions/determine_version.py (this generates e.g. --version-suffix +rocm7.10.0)
  • build_tools/github_actions/tests/determine_version_test.py
• build_tools/github_actions/write_jax_versions.py (this finds the versions in built packages)
• build_tools/github_actions/generate_jax_manifest.py (this records versions into a manifest file)
  • build_tools/github_actions/tests/generate_jax_manifest_test.py
• In the ROCm/rocm-jax repository: build/ci_build (see the --rocm-version and --no-rocm-version-extra flags)

Versions for each distribution channel:

Working with Python package versions

When working with versions please use these tools and avoid custom parsing (such as regex) if possible:

• The packaging.version Python module: https://packaging.pypa.io/en/stable/version.html

  For example:

  >>> from packaging.version import Version
  >>> v1 = Version("1.1.0")
  >>> v2 = Version("1.2.0+abc")
  >>> v2 > v1
  True
  >>> v2.base_version
  '1.2.0'
  

• packaging.specifiers.SpecifierSet for testing constraints written as dependency specifiers:

  >>> from packaging.specifiers import SpecifierSet
  >>> from packaging.version import Version
  >>> same_minor = SpecifierSet("==7.14.*")
  >>> Version("7.14.0.post1") in same_minor
  True
  >>> Version("7.15.0") in same_minor
  False
  >>> same_major_from_7_14 = SpecifierSet("~=7.14")
  >>> Version("7.15.0") in same_major_from_7_14
  True
  >>> Version("8.0.0") in same_major_from_7_14
  False
  

• Existing Python scripts:

  • build_tools/compute_rocm_package_version.py
  • build_tools/github_actions/determine_version.py
  • build_tools/github_actions/write_torch_versions.py
  • build_tools/github_actions/generate_pytorch_source_manifest.py
  • external-builds/pytorch/checkout_from_manifest.py

Tip - installing prereleases

Python package installers like pip ignore pre-releases by default if a final release exists unless explicitly requested with e.g. pip install rocm==7.10.0rc0 or pip install --pre rocm. See also Python Packaging User Guide - Versioning.

Tip - Upgrading and force reinstalling

The --upgrade and --force-reinstall options can also be useful when switching between version types to ensure that the expected package versions are used. See the documentation for pip install.

Tip - checking package versions

A few ways to look up the version of an installed package are:

• pip show:

  $ pip show torch | grep Version
  Version: 2.10.0a0+rocm7.11.0a20251209
  

• pip list:

  $ pip list | grep torch
  torch                          2.10.0a0+rocm7.11.0a2025120
  

• pip freeze:

  $ pip freeze | grep torch
  torch==2.10.0a0+rocm7.11.0a20251209
  

• The __version__ module attribute:

  $ python -c "import torch; print(torch.__version__)"
  2.10.0a0+rocm7.11.0a20251209
  

Native Linux package versions

TheRock supports rpm and debian packages. Each has different versioning scheme as mentioned below. Native package versions are handled by scripts:

• build_tools/compute_rocm_package_version.py
  • build_tools/tests/compute_rocm_package_version_test.py

The script produces these versions for rpm packages for each release type:

The script produces these versions for debian packages for each release type:

>>> from debian.debian_support import NativeVersion
>>> NativeVersion("7.10.0~20251124") > NativeVersion("7.10.0~dev20251124")
False

Working with Debian package versions

The python-debian package can be used to work with debian package versions:

• https://pypi.org/project/python-debian/
• https://salsa.debian.org/python-debian-team/python-debian
• https://python-debian-team.pages.debian.net/python-debian/html/api/debian.debian_support.html

Native Windows package versions

TODO: fill this in together with https://github.com/ROCm/TheRock/pull/2159