versioning.md

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)
• 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, while subprojects may have their own independent library versions (for example HIPBLASLT_PROJECT_VERSION in rocm-libraries/projects/hipblaslt/CMakeLists.txt).

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.

Distribution channel	Base URL	Source of builds
stable releases	https://repo.amd.com/rocm/	Manually promoted prereleases
prereleases	https://rocm.prereleases.amd.com/	Manually triggered workflows in rockrel
nightly releases	https://rocm.nightlies.amd.com/	Scheduled workflows in TheRock
dev releases	https://rocm.devreleases.amd.com/	Manually triggered test workflows in TheRock
dev builds	No central index	Local builds and per-commit workflows in TheRock, rocm-libraries, rocm-systems, etc.

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.

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:

Release type	Version format	Version example
stable	X.Y.Z	7.10.0
prerelease	X.Y.ZrcN	7.10.0rc0 (The first release candidate for that stable release)
nightly	X.Y.ZaYYYYMMDD	7.10.0a20251124 (The nightly release on 2025-11-24)
dev	X.Y.Z.dev0+NNNN	7.10.0.dev0+efed3c3b10a5cce8578f58f8eb288582c26d18c4 (For commit efed3c3)

Each distribution channel (and GPU family within that channel) is currently hosted on a separate release index that can be passed to pip or uv via --index-url. For example:

pip install --index-url=https://rocm.nightlies.amd.com/v2/gfx94X-dcgpu/ rocm

See RELEASES.md - Installing releases using pip for details.

Note

We plan on later providing a single multi-architecture index as part of multi-arch work, see RFC0008-Multi-Arch-Packaging.md - Python Packaging.

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:

ROCm release type	ROCm version example	Composite torch version example
stable	7.10.0	2.9.0+rocm7.10.0
nightly	7.10.0a20251124	2.9.0+rocm7.10.0a20251124
dev	7.10.0.dev0+efed3c	2.9.0+devrocm7.10.0.dev0-efed3c (Note the devrocm and - instead of +)

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

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)

The scripts produce these versions for each distribution channel:

Package name	Example release version (stable x stable)	Example nightly version (nightly x nightly)
torch	2.9.1+rocm7.10.0	2.10.0a0+rocm7.10.0a20251024
torchaudio	2.9.0+rocm7.10.0	2.10.0a0+rocm7.10.0a20251024
torchvision	0.24.0+rocm7.10.0	0.24.0+rocm7.11.0a20251124
triton	3.3.1+rocm7.10.0	3.5.1+rocm7.11.0a20251124

JAX versions

TODO: fill this in together with:

• #1985
• #2091

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'

• 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

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_native_package_version.py
  • build_tools/tests/compute_rocm_native_package_version_test.py

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

Release type	Version format	Version example
stable	X.Y.Z	7.10.0
prerelease	X.Y.Z~rcN	7.10.0~rc0 (The first release candidate for that stable release)
nightly	X.Y.Z~YYYYMMDD	7.10.0~20251124 (The nightly release on 2025-11-24)
dev	X.Y.Z~YYYYMMDDg<git-hash>	7.10.0~20251124gefed3c3 (For commit efed3c3)

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

Release type	Version format	Version example
stable	X.Y.Z	7.10.0
prerelease	X.Y.Z~preN	7.10.0~pre0 (The first release candidate for that stable release)
nightly	X.Y.Z~YYYYMMDD	7.10.0~20251124 (The nightly release on 2025-11-24)
dev	X.Y.Z~devYYYYMMDD	7.10.0~dev20251124 (For dev build on 2025-11-24)d18c4)

Native Windows package versions

TODO: fill this in together with #2159