From cdc5d34687ab39f528c172f0078dfdb9c7a47286 Mon Sep 17 00:00:00 2001 From: pmoutsias-amd Date: Fri, 2 Oct 2026 14:42:18 -0400 Subject: [PATCH 1/6] docs: port v0.1.0 doc restructure from main (PR #473) Bring PR #473's editorial and structural changes onto the 0.1.0 docs, minus every description of functionality that shipped after the 0.1.0 cut. The 0.1.0 branch has no `rocm remote`, no `rocm install sdk --devel` toolchain concept, no `rocm services list --json`, and none of the prune-wait or storage-report additions, so the README and docs/vllm.md prose that describes them stays out. README: - Split the `install sdk` prose and add a `##### ROCm 10 and newer` heading; omit the `--devel` subsection. - Editorial: approval-prompt sentence, `--approve-replacing-active-default` and install-location line wraps, update table `Effect` -> `Description` with the `--apply` "never prompts" wording, the "Nothing about this happens on its own" paragraph, and the em-dash -> period fix in the `qwen` serve paragraph. docs/vllm.md: - Heading promotion and `ROCm CLI` naming throughout, the env-var placeholder rewording, and the Related resources titled links. Omit the `--devel` source-build paragraph. - The result is byte-identical to main's file except that paragraph. Docs site: - Add docs/rocm-docs/engines/vllm.md, transcluding docs/vllm.md. - Regroup index.rst and _toc.yml.in: Demos under Getting started, Commands -> Use ROCm CLI with Command reference before vLLM adapter. - Add the Command reference intro sentence, the getting-started copy comment, and swap installation.md's vLLM link for the new page. CI: - Add docs/vllm.md to the docs path filter, since the new page transcludes it and a later edit to it alone must not skip the -W docs build. Verified with the same Sphinx build CI runs, `sphinx-build -W`: the new page renders and the nav resolves with no warnings. Every `:start-after:` anchor in the including pages still matches README.md exactly once. Signed-off-by: pmoutsias-amd --- .github/workflows/ci.yml | 7 ++- README.md | 25 +++++---- docs/rocm-docs/commands.md | 4 ++ docs/rocm-docs/engines/vllm.md | 8 +++ docs/rocm-docs/getting-started.md | 6 +- docs/rocm-docs/index.rst | 8 +-- docs/rocm-docs/install/installation.md | 2 +- docs/rocm-docs/sphinx/_toc.yml.in | 11 ++-- docs/vllm.md | 78 ++++++++++++++------------ 9 files changed, 88 insertions(+), 61 deletions(-) create mode 100644 docs/rocm-docs/engines/vllm.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2a1489b78..e56f519dd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -160,13 +160,14 @@ jobs: - 'ruff.toml' - 'PSScriptAnalyzerSettings.psd1' - '.github/workflows/**' - # Sphinx docs site: the doc sources themselves, plus README.md and - # CONTRIBUTING.md, which several pages single-source via MyST - # `{include}` directives, plus the build config/toolchain pins. + # Sphinx docs site: the doc sources themselves, plus README.md, + # CONTRIBUTING.md and docs/vllm.md, which pages single-source via + # MyST `{include}` directives, plus the build config/toolchain pins. docs: - 'docs/rocm-docs/**' - 'README.md' - 'CONTRIBUTING.md' + - 'docs/vllm.md' - '.readthedocs.yaml' - '.github/workflows/**' diff --git a/README.md b/README.md index ddaaec832..08f1cba37 100644 --- a/README.md +++ b/README.md @@ -216,7 +216,7 @@ rocm serve qwen ``` `qwen` is a built-in alias for a small assistant model that serves out of the -box. You can also serve any compatible Hugging Face model directly — see +box. You can also serve any compatible Hugging Face model directly. See [Model serving](#model-serving) for the GGUF-vs-safetensors rule, since which form works depends on the engine your GPU selects. @@ -317,13 +317,13 @@ by rocm-cli. If no managed runtime is the active default, `install sdk` doesn't prompt. Otherwise it asks first, because the new install becomes the active default. The prompt applies to any install, including a `--family` or `--channel` you -haven't installed before. +haven't installed before, just as it does for a same-family upgrade. To approve without a prompt, for example in scripts or CI, where the prompt would otherwise refuse: -- `--approve-replacing-active-default` approves the change of active default - only. The refusal message recommends it, and ROCm CLI's own non-interactive +- `--approve-replacing-active-default` approves the change of active default. + The refusal message recommends it, and ROCm CLI's own non-interactive surfaces (chat, MCP, and the dashboard) pass it. - `--yes` gives the same approval and also approves installing required system packages, such as OpenMPI for vLLM. That requires `sudo`, so use it only where @@ -338,8 +338,8 @@ same-version reinstall reuses the same root. `--prefix` changes this. The folder you name is used as-is for every version, so successive installs into one prefix replace each other in place. If the venv -already there no longer runs its own Python, it is removed outright and rebuilt. The -approval prompt doesn't cover this, because it asks only about changing the +already there no longer runs its own Python, it is removed outright and rebuilt. +The approval prompt doesn't cover this, because it asks only about changing the active default runtime, not about what a named prefix loses. #### Driver installation @@ -351,15 +351,17 @@ package. `update` checks for a newer ROCm package. -| Flag | Effect | +| Flag | Description | | --- | --- | -| `--apply` | Installs the update. Needs no approval flag, because selecting a runtime to update is the approval. Leaves the active default alone unless you add `--activate`. | +| `--apply` | Installs the update. Never prompts and needs no approval flag, because selecting a runtime to update is the approval. Leaves the active default alone unless you add `--activate`. | | `--dry-run` | Previews what `--apply` would do without changing anything. Doesn't require `--apply`. | | `--runtime`, `--activate` | Require `--apply` or `--dry-run`. | | `--json` | Prints the check result as a single line of JSON instead of text. Conflicts with `--apply` and `--dry-run`. | | `--timeout-secs` | Bounds the network calls of the check. Requires `--json`. Conflicts with `--apply`. | | `--yes` | Accepted for consistency with other mutating commands, but grants nothing on `update`. The approval line the update path prints never credits it. | +#### ROCm 10 and newer + ROCm 10 and newer ship from a different source layout. You opt in by passing two things together: pin the version with `--version`, and name the exact GPU arch, using the raw `gfx` code rather than a family label: @@ -378,9 +380,10 @@ torchaudio from their published dependency metadata, then validates that every selected framework package carries the same ROCm build identifier before it creates or changes a managed runtime. -Without a `--version` of 10 or newer, `install sdk` resolves the same release -and nightly sources as before. It doesn't retry against the ROCm 10 sources when -a lookup finds nothing; it tells you what it couldn't find instead. +Nothing about this happens on its own. Without a `--version` of 10 or newer, +`install sdk` resolves the same release and nightly sources as before. It doesn't +quietly retry against the ROCm 10 sources when a lookup finds nothing; it tells +you what it couldn't find instead. ### Runtime management diff --git a/docs/rocm-docs/commands.md b/docs/rocm-docs/commands.md index 02e368053..e9d5f8e92 100644 --- a/docs/rocm-docs/commands.md +++ b/docs/rocm-docs/commands.md @@ -6,6 +6,10 @@ SPDX-License-Identifier: MIT # Command reference +This page describes each `rocm` command, its options, and what it does. For a +short list of the commands and what each is for, see +[Getting started](getting-started.md). + ```{include} ../../README.md :start-after: "## Commands" :end-before: "and a chat tab backed by any configured provider." diff --git a/docs/rocm-docs/engines/vllm.md b/docs/rocm-docs/engines/vllm.md new file mode 100644 index 000000000..732a57e14 --- /dev/null +++ b/docs/rocm-docs/engines/vllm.md @@ -0,0 +1,8 @@ + + +```{include} ../../vllm.md +``` diff --git a/docs/rocm-docs/getting-started.md b/docs/rocm-docs/getting-started.md index 525ea51e5..6a25b6efd 100644 --- a/docs/rocm-docs/getting-started.md +++ b/docs/rocm-docs/getting-started.md @@ -18,6 +18,10 @@ SPDX-License-Identifier: MIT :end-before: "Running the command when a" ``` + Running the command when a managed runtime is already the active default asks first, because the new install takes over as the active default; see [ROCm installation](commands.md#rocm-installation) for that gate and the flags @@ -28,7 +32,7 @@ that approve it without a prompt. :end-before: "You can also serve any compatible Hugging Face model directly" ``` -You can also serve any compatible Hugging Face model directly — see +You can also serve any compatible Hugging Face model directly. See [Model serving](commands.md#model-serving) for the GGUF-vs-safetensors rule, since which form works depends on the engine your GPU selects. diff --git a/docs/rocm-docs/index.rst b/docs/rocm-docs/index.rst index cda28a9e8..f6ec6fbd2 100644 --- a/docs/rocm-docs/index.rst +++ b/docs/rocm-docs/index.rst @@ -26,10 +26,6 @@ The ROCm CLI public repository is located at .. grid:: 2 :gutter: 3 - .. grid-item-card:: Demos - - * :doc:`See ROCm CLI in action ` - .. grid-item-card:: Install * :doc:`Installing ROCm CLI ` @@ -37,7 +33,9 @@ The ROCm CLI public repository is located at .. grid-item-card:: Getting started * :doc:`Getting started with ROCm CLI ` + * :doc:`See ROCm CLI in action ` - .. grid-item-card:: Commands + .. grid-item-card:: Use ROCm CLI * :doc:`Command reference ` + * :doc:`vLLM adapter ` diff --git a/docs/rocm-docs/install/installation.md b/docs/rocm-docs/install/installation.md index 94917a562..53cabf3e1 100644 --- a/docs/rocm-docs/install/installation.md +++ b/docs/rocm-docs/install/installation.md @@ -16,7 +16,7 @@ ROCm CLI ships as a single prebuilt binary. Platform support: Live dashboard telemetry requires Linux or WSL2 (see [Interactive interfaces](../getting-started.md#interactive-interfaces)). vLLM serving is Linux or WSL2 only (see -[docs/vllm.md](https://github.com/ROCm/rocm-cli/blob/main/docs/vllm.md)). +[vLLM adapter](../engines/vllm.md)). ```{include} ../../../README.md :start-after: "only (see [docs/vllm.md](docs/vllm.md))." diff --git a/docs/rocm-docs/sphinx/_toc.yml.in b/docs/rocm-docs/sphinx/_toc.yml.in index 7534a1eaa..3494fbd4b 100644 --- a/docs/rocm-docs/sphinx/_toc.yml.in +++ b/docs/rocm-docs/sphinx/_toc.yml.in @@ -1,18 +1,19 @@ root: index subtrees: - - caption: Demos - entries: - - file: demos - title: See ROCm CLI in action - caption: Install entries: - file: install/installation - caption: Getting started entries: - file: getting-started - - caption: Commands + - file: demos + title: See ROCm CLI in action + - caption: Use ROCm CLI entries: - file: commands + title: Command reference + - file: engines/vllm + title: vLLM adapter - caption: About entries: - file: about/contributing diff --git a/docs/vllm.md b/docs/vllm.md index 71d66a07d..06cee28fe 100644 --- a/docs/vllm.md +++ b/docs/vllm.md @@ -4,26 +4,29 @@ Copyright © Advanced Micro Devices, Inc., or its affiliates. SPDX-License-Identifier: MIT --> -# vLLM Adapter +# vLLM adapter `rocm-engine-vllm` is a first-party adapter around an existing vLLM installation. It is intended for Linux and WSL ROCm GPU serving. The adapter does not install vLLM automatically and does not run CPU mode. Install or build vLLM in a ROCm-capable Python environment first, then make the -`vllm` command visible to rocm-cli. +`vllm` command visible to ROCm CLI. -For rocm-cli managed TheRock runtimes, prefer building vLLM from source against +Native Windows vLLM serving is skipped in this adapter. Use WSL or Linux for vLLM +ROCm serving, or choose a different engine explicitly. No CPU fallback is used. + +For ROCm CLI-managed TheRock runtimes, prefer building vLLM from source against the existing TheRock PyTorch stack. A prebuilt vLLM ROCm wheel can replace the TheRock torch packages or target a different ROCm soname set; that is not a -valid no-fallback setup for rocm-cli GPU serving. +valid no-fallback setup for ROCm CLI GPU serving. ## Torch alignment on engine install Installing an engine into a managed TheRock runtime can change the torch in that -runtime. Two installers write torch into the same environment — the SDK install +runtime. Two installers write torch into the same environment: the SDK install writes TheRock's build, and the engine install then writes the build from its own -index — so `rocm engines install` settles which one stays and prints the result +index. So `rocm engines install` settles which one stays and prints the result as a `torch_alignment:` line. A torch that already executes a GPU kernel against the installed SDK is kept @@ -41,19 +44,19 @@ skip the replacement: ROCM_CLI_DISABLE_TORCH_ALIGNMENT=1 rocm engines install vllm --yes ``` -Any value works, including an empty one — the variable being set is the signal. +Any value works, including an empty one: the variable being set is the signal. The install then reports `torch_alignment: disabled`, naming both the build it would have installed and the one it kept. The device check still runs, so an opt-out that leaves the runtime unable to serve says so rather than failing later during serving. -Use it when you are deliberately running a torch the alignment would replace — a -locally built wheel, a version under test, a stack pinned for a reproduction. It +Use it when you are deliberately running a torch the alignment would replace (a +locally built wheel, a version under test, or a stack pinned for a reproduction). It is an escape hatch, not a supported configuration: the resulting combination is not validated against the supported matrix, and a runtime that cannot execute a kernel will fail at serving time. -### ROCm 10.x wheel discovery +## ROCm 10.x wheel discovery For most ROCm SDK versions, `rocm engines install vllm` pins a fixed vLLM wheel and index URL. Any ROCm SDK 10.x version is different: AMD publishes vLLM, @@ -76,11 +79,13 @@ likely install an ABI-incompatible build, so the install fails closed instead with a message naming the detected version and pointing at `ROCM_CLI_VLLM_ROCM_INDEX_URL` as the way to install anyway. +## Discovery paths and checks + Supported discovery paths: -- `ROCM_CLI_VLLM_COMMAND=/path/to/vllm` -- `ROCM_CLI_VLLM_PYTHON=/path/to/python` where a sibling `vllm` command exists -- the active rocm-cli managed TheRock runtime, if vLLM has been installed into +- `ROCM_CLI_VLLM_COMMAND=path_to_vllm`, where `path_to_vllm` is the absolute path to the `vllm` executable +- `ROCM_CLI_VLLM_PYTHON=path_to_python`, where `path_to_python` is the absolute path to a Python interpreter that has a sibling `vllm` command +- the active ROCm CLI-managed TheRock runtime, if vLLM has been installed into that Python environment - `vllm` on `PATH` @@ -93,7 +98,9 @@ rocm-engine-vllm resolve-model Qwen/Qwen3.5-4B --device-policy gpu_required python scripts/vllm_therock_gpu_test.py --self-test ``` -GPU acceptance check: +## GPU acceptance check + +Run the acceptance script against a built adapter: ```bash python3 scripts/vllm_therock_gpu_test.py \ @@ -101,14 +108,16 @@ python3 scripts/vllm_therock_gpu_test.py \ --model facebook/opt-125m ``` -The acceptance script is Linux/WSL only. It requires vLLM to be discoverable -through a rocm-cli managed TheRock runtime manifest, launches with +The acceptance script is Linux or WSL only. It requires vLLM to be discoverable +through a ROCm CLI-managed TheRock runtime manifest, launches with `gpu_required`, checks `/health` and `/v1/completions`, and verifies loaded ROCm libraries come from the managed TheRock SDK wheel directories. It rejects external vLLM command overrides and does not allow CPU fallback. It defaults to the active exact runtime key; if `--runtime-id` is passed, use an exact runtime key or an unambiguous runtime id. +### Source build notes + On WSL, the tested source build needed vLLM ROCm platform detection to use TheRock PyTorch device data when `amdsmi` is unavailable, and needed vLLM's ROCm GPTQ half-atomic compatibility path enabled for TheRock 7.13 headers. @@ -128,13 +137,15 @@ kernel. With the patch, the live acceptance harness passed on `facebook/opt-125m` and verified HIP/BLAS libraries loaded from the managed TheRock SDK wheel directories. -Serving through rocm-cli: +## Serve a model + +Serve a model through ROCm CLI: ```bash rocm serve Qwen/Qwen3.5-4B --engine vllm --device gpu_required --managed ``` -### GPU selection +## GPU selection Use `--gpu` to choose the AMD GPU vLLM runs on: @@ -146,17 +157,17 @@ rocm serve Qwen/Qwen3.5-4B --engine vllm --managed rocm serve Qwen/Qwen3.5-4B --engine vllm --gpu 1 --managed ``` -rocm-cli pins the device via `HIP_VISIBLE_DEVICES`. Serving one model across +ROCm CLI pins the device via `HIP_VISIBLE_DEVICES`. Serving one model across multiple GPUs is not supported. -### GPU memory +## GPU memory -vLLM claims a fixed fraction of each GPU's **total** VRAM — not of the free -VRAM, and not scaled to the model — for weights plus KV cache. On a large card +vLLM claims a fixed fraction of each GPU's **total** VRAM (not of the free +VRAM, and not scaled to the model) for weights plus KV cache. On a large card a small model therefore still reserves a large slice. -rocm-cli sets no `--gpu-memory-utilization` of its own, so vLLM's own default -applies unless a value comes from somewhere else — either a model's catalog +ROCm CLI sets no `--gpu-memory-utilization` of its own, so vLLM's own default +applies unless a value comes from somewhere else: either a model's catalog recipe or, taking precedence over it, the flag below: ```bash @@ -165,7 +176,7 @@ rocm serve --engine vllm --gpu-memory-utilization 0.3 --managed The value is a fraction in `(0, 1]` of total device VRAM. Lower it to leave room for a display, another workload, or a second server; raise it to give a large -model more KV cache. Applies to vLLM only — it is ignored, with a note in the +model more KV cache. Applies to vLLM only; it is ignored, with a note in the serve output, for other engines. An out-of-range or unparsable value fails the command rather than falling back silently. @@ -173,16 +184,16 @@ Earlier releases pinned this to `0.80` to leave display/WSL headroom. That pin i gone, so an unchanged command now reserves vLLM's own (higher) default. Pass `--gpu-memory-utilization 0.8` to restore the previous reservation. -### Tool calling +## Tool calling The TUI chat tab attaches tool definitions to every chat request. vLLM rejects those with HTTP 400 unless it is launched with `--enable-auto-tool-choice` **and** a matching `--tool-call-parser`. vLLM does not auto-detect the parser and it is -model-specific, so rocm-cli never guesses one: +model-specific, so ROCm CLI never guesses one: - **Built-in catalog models** carry the correct parser in their recipe metadata, - so tool calling works out of the box (e.g. Qwen family → `hermes`, - Llama 3 → `llama3_json`). + so tool calling works out of the box (for example, Qwen family → `hermes`, + Llama 3 → `llama3_json`). - **Other models** (arbitrary Hugging Face repos, or a catalog model forced onto vLLM without authored metadata) need an explicit parser: @@ -194,10 +205,7 @@ model-specific, so rocm-cli never guesses one: default, and applies to vLLM only. Common values: `hermes`, `llama3_json`, `mistral`. Without it, plain chat still works but tool calls return HTTP 400. -Native Windows vLLM serving is skipped in this adapter. Use WSL/Linux for vLLM -ROCm serving, or choose a different engine explicitly. No CPU fallback is used. - -References: +## Related resources -- vLLM ROCm installation: https://docs.vllm.ai/en/stable/getting_started/installation/gpu/ -- AMD ROCm vLLM guidance: https://rocmdocs.amd.com/en/latest/how-to/rocm-for-ai/inference/deploy-your-model.html +- [vLLM ROCm installation](https://docs.vllm.ai/en/stable/getting_started/installation/gpu/) +- [AMD ROCm AI ecosystem: vLLM](https://rocm.docs.amd.com/projects/ai-ecosystem/en/latest/inference/vllm.html) From d2a01faff39ff6db430f69db43320bbf11b47776 Mon Sep 17 00:00:00 2001 From: pmoutsia_amdeng Date: Wed, 7 Oct 2026 19:04:30 -0400 Subject: [PATCH 2/6] docs: call out supported ROCm versions (7.14, 10.0, 10.1) Document that ROCm CLI supports multiple ROCm versions, and that ROCm 10.0 and newer install from a different source layout. - README.md: note the supported versions at the install sdk step, extend the existing ROCm installation cross-reference to cover the ROCm 10 and newer requirements, and align "and newer" wording throughout. - getting-started.md: carry the same note and retarget the cross-reference. --- README.md | 15 ++++++++++----- docs/rocm-docs/getting-started.md | 12 ++++++------ 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 08f1cba37..484cdf832 100644 --- a/README.md +++ b/README.md @@ -203,11 +203,16 @@ rocm install sdk This downloads TheRock ROCm wheels and a matching PyTorch stack into a managed environment. On machines with an existing ROCm install, `rocm examine` will show it as `legacy_rocm_status: detected_unmanaged` — running `rocm install sdk` -creates a separate managed runtime alongside it. Running the command when a -managed runtime is already the active default asks first, because the new -install takes over as the active default; see +creates a separate managed runtime alongside it. + +`rocm install sdk` can install ROCm 7.14, 10.0, or 10.1. For ROCm 10.0 and +newer, pin the version and name the exact GPU arch. + +Running the command when a managed runtime is already the active default asks +first, because the new install takes over as the active default; see [ROCm installation](https://github.com/ROCm/rocm-cli/blob/main/README.md#rocm-installation) -for that gate and the flags that approve it without a prompt. +for that gate, the flags that approve it without a prompt, and the ROCm 10 and +newer requirements. Then serve a model: @@ -367,7 +372,7 @@ things together: pin the version with `--version`, and name the exact GPU arch, using the raw `gfx` code rather than a family label: ``` -rocm install sdk --version 10.0.0 --family gfx1200 --dry-run +rocm install sdk --version 10.1.0 --family gfx1200 --dry-run ``` A family label such as `--family gfx120X-all` is rejected for those versions diff --git a/docs/rocm-docs/getting-started.md b/docs/rocm-docs/getting-started.md index 6a25b6efd..86bfab3a9 100644 --- a/docs/rocm-docs/getting-started.md +++ b/docs/rocm-docs/getting-started.md @@ -19,16 +19,16 @@ SPDX-License-Identifier: MIT ``` + cross-reference retargeted to this site. The end of the sentence is then + reused as the `:start-after:` anchor for the next include, which also + matches the original sentence in README.md; edit both together. --> Running the command when a managed runtime is already the active default asks first, because the new install takes over as the active default; see -[ROCm installation](commands.md#rocm-installation) for that gate and the flags -that approve it without a prompt. +[ROCm installation](commands.md#rocm-installation) for that gate, the flags +that approve it without a prompt, and the ROCm 10 and newer requirements. ```{include} ../../README.md -:start-after: "for that gate and the flags that approve it without a prompt." +:start-after: "newer requirements." :end-before: "You can also serve any compatible Hugging Face model directly" ``` From 2240192ec784caa5a4680bd6f5c2f37863e272ec Mon Sep 17 00:00:00 2001 From: pmoutsia_amdeng Date: Thu, 8 Oct 2026 17:48:51 -0400 Subject: [PATCH 3/6] docs: state the default ROCm version and move the ROCm 10 section - README.md: say that install sdk installs ROCm 7.14 by default and that ROCm 10.0 and newer are opt-in, at the install sdk step and in the ROCm installation intro. - README.md: move "ROCm 10 and newer" up beside the other install sdk subsections, so it no longer follows the unrelated Updates section. --- README.md | 41 +++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 484cdf832..f04ee98d0 100644 --- a/README.md +++ b/README.md @@ -205,7 +205,7 @@ environment. On machines with an existing ROCm install, `rocm examine` will show it as `legacy_rocm_status: detected_unmanaged` — running `rocm install sdk` creates a separate managed runtime alongside it. -`rocm install sdk` can install ROCm 7.14, 10.0, or 10.1. For ROCm 10.0 and +By default, `rocm install sdk` installs ROCm 7.14. To install ROCm 10.0 or newer, pin the version and name the exact GPU arch. Running the command when a managed runtime is already the active default asks @@ -315,7 +315,8 @@ rocm update [--apply] [--runtime KEY] [--activate] [--dry-run] ``` `install sdk` downloads TheRock ROCm wheels into a Python environment managed -by rocm-cli. +by rocm-cli. By default it installs ROCm 7.14. To install ROCm 10.0 or newer, +follow the steps under ROCm 10 and newer, below. #### Approval prompt @@ -347,24 +348,6 @@ already there no longer runs its own Python, it is removed outright and rebuilt. The approval prompt doesn't cover this, because it asks only about changing the active default runtime, not about what a named prefix loses. -#### Driver installation - -`install driver` installs the AMD kernel driver on Linux, using DKMS or a native -package. - -#### Updates - -`update` checks for a newer ROCm package. - -| Flag | Description | -| --- | --- | -| `--apply` | Installs the update. Never prompts and needs no approval flag, because selecting a runtime to update is the approval. Leaves the active default alone unless you add `--activate`. | -| `--dry-run` | Previews what `--apply` would do without changing anything. Doesn't require `--apply`. | -| `--runtime`, `--activate` | Require `--apply` or `--dry-run`. | -| `--json` | Prints the check result as a single line of JSON instead of text. Conflicts with `--apply` and `--dry-run`. | -| `--timeout-secs` | Bounds the network calls of the check. Requires `--json`. Conflicts with `--apply`. | -| `--yes` | Accepted for consistency with other mutating commands, but grants nothing on `update`. The approval line the update path prints never credits it. | - #### ROCm 10 and newer ROCm 10 and newer ship from a different source layout. You opt in by passing two @@ -390,6 +373,24 @@ Nothing about this happens on its own. Without a `--version` of 10 or newer, quietly retry against the ROCm 10 sources when a lookup finds nothing; it tells you what it couldn't find instead. +#### Driver installation + +`install driver` installs the AMD kernel driver on Linux, using DKMS or a native +package. + +#### Updates + +`update` checks for a newer ROCm package. + +| Flag | Description | +| --- | --- | +| `--apply` | Installs the update. Never prompts and needs no approval flag, because selecting a runtime to update is the approval. Leaves the active default alone unless you add `--activate`. | +| `--dry-run` | Previews what `--apply` would do without changing anything. Doesn't require `--apply`. | +| `--runtime`, `--activate` | Require `--apply` or `--dry-run`. | +| `--json` | Prints the check result as a single line of JSON instead of text. Conflicts with `--apply` and `--dry-run`. | +| `--timeout-secs` | Bounds the network calls of the check. Requires `--json`. Conflicts with `--apply`. | +| `--yes` | Accepted for consistency with other mutating commands, but grants nothing on `update`. The approval line the update path prints never credits it. | + ### Runtime management Manage multiple side-by-side ROCm runtimes: From bbb25e913a4a51f79b8e90138acc9880b9f13f51 Mon Sep 17 00:00:00 2001 From: pmoutsia_amdeng Date: Thu, 8 Oct 2026 17:53:37 -0400 Subject: [PATCH 4/6] docs: show the ROCm 10 install command in getting started Add an example install sdk command with --version and --family at the install sdk step, so readers don't have to open the ROCm 10 and newer section to see what the opt-in looks like. --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f04ee98d0..d34e260e1 100644 --- a/README.md +++ b/README.md @@ -206,7 +206,13 @@ show it as `legacy_rocm_status: detected_unmanaged` — running `rocm install sd creates a separate managed runtime alongside it. By default, `rocm install sdk` installs ROCm 7.14. To install ROCm 10.0 or -newer, pin the version and name the exact GPU arch. +newer, pin the version and name the exact GPU arch, for example: + +``` +rocm install sdk --version 10.1.0 --family gfx1200 +``` + +Replace `gfx1200` with the arch that `rocm examine` reports. Running the command when a managed runtime is already the active default asks first, because the new install takes over as the active default; see From a6a2b3cbae8f6c887b6cfb450f2132d70b6213d6 Mon Sep 17 00:00:00 2001 From: pmoutsia_amdeng Date: Thu, 8 Oct 2026 17:57:35 -0400 Subject: [PATCH 5/6] docs: clarify --family takes a raw gfx code for ROCm 10 Say that ROCm 10.0 and newer need --version plus --family set to the exact GPU arch as a raw gfx code, not a family label, so --family doesn't read as a ROCm 10-only flag. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d34e260e1..bd63c868d 100644 --- a/README.md +++ b/README.md @@ -206,7 +206,8 @@ show it as `legacy_rocm_status: detected_unmanaged` — running `rocm install sd creates a separate managed runtime alongside it. By default, `rocm install sdk` installs ROCm 7.14. To install ROCm 10.0 or -newer, pin the version and name the exact GPU arch, for example: +newer, pin the version with `--version` and set `--family` to the exact GPU +arch as a raw `gfx` code, not a family label such as `gfx120X-all`: ``` rocm install sdk --version 10.1.0 --family gfx1200 From 8067f7141918caf590aa8462547616043f4bf7cc Mon Sep 17 00:00:00 2001 From: pmoutsia_amdeng Date: Thu, 8 Oct 2026 17:59:27 -0400 Subject: [PATCH 6/6] docs: trim the ROCm 10 note in getting started Replace the example block with a short inline example, and drop the duplicate default-version claim from the ROCm installation intro so the default is stated in one place. --- README.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index bd63c868d..b04a23a02 100644 --- a/README.md +++ b/README.md @@ -205,15 +205,9 @@ environment. On machines with an existing ROCm install, `rocm examine` will show it as `legacy_rocm_status: detected_unmanaged` — running `rocm install sdk` creates a separate managed runtime alongside it. -By default, `rocm install sdk` installs ROCm 7.14. To install ROCm 10.0 or -newer, pin the version with `--version` and set `--family` to the exact GPU -arch as a raw `gfx` code, not a family label such as `gfx120X-all`: - -``` -rocm install sdk --version 10.1.0 --family gfx1200 -``` - -Replace `gfx1200` with the arch that `rocm examine` reports. +By default, `rocm install sdk` installs ROCm 7.14. For ROCm 10.0 or newer, add +`--version` and `--family` with the exact GPU arch from `rocm examine`, for +example `--version 10.1.0 --family gfx1200`. Running the command when a managed runtime is already the active default asks first, because the new install takes over as the active default; see @@ -322,7 +316,7 @@ rocm update [--apply] [--runtime KEY] [--activate] [--dry-run] ``` `install sdk` downloads TheRock ROCm wheels into a Python environment managed -by rocm-cli. By default it installs ROCm 7.14. To install ROCm 10.0 or newer, +by rocm-cli. It can install ROCm 7.14, 10.0, or 10.1. To install 10.0 or newer, follow the steps under ROCm 10 and newer, below. #### Approval prompt