[Doc] [ROCm] Update installation documentation (#52303)
Signed-off-by: tjtanaa <tunjian.tan@embeddedllm.com>
TJian committed
Aug 17, 2026 at 16:56 UTC
c05d923f186842d4ac35bfddafdd5aa01b6cbaf8
1 file changed
+71
docs/getting_started/installation/gpu.rocm.inc.md
+71
@@ -154,6 +154,77 @@ uv pip install vllm==${VLLM_VERSION} \
154
--8<-- [end:pre-built-wheels]
155
--8<-- [start:build-wheel-from-source]
156
157
+#### Set up using Python-only build (without compilation) {#python-only-build}
158
+
159
+If you only need to change Python code, you can build and install vLLM without
160
+compilation. Changes you make to the code will be reflected when you run vLLM:
161
+
162
+```bash
163
+git clone https://github.com/vllm-project/vllm.git
164
+cd vllm
165
+VLLM_USE_PRECOMPILED=1 python3 setup.py develop
166
+```
167
+
168
+This command will do the following:
169
+
170
+1. Look for the current branch in your vLLM clone.
171
+1. Identify the corresponding base commit in the main branch.
172
+1. Detect the ROCm version in your environment and select the matching wheel
173
+ variant.
174
+1. Download the pre-built wheel of the base commit.
175
+1. Use its compiled libraries and `vllm-rs` binary in the installation.
176
+
177
+!!! note
178
+ 1. If you change C++, HIP, or kernel code, you cannot use Python-only build;
179
+ otherwise you may see an import error about a library not being found or
180
+ an undefined symbol.
181
+ 2. If you rebase your development branch, it is recommended to uninstall
182
+ vLLM and re-run the above command to make sure your libraries are up to
183
+ date.
184
+
185
+!!! tip "Rebuilding the Rust frontend"
186
+If you need to recompile the `vllm-rs` Rust frontend binary, you can rebuild and
187
+install it without re-running the full installation:
188
+
189
+ ```bash
190
+ ./build_rust.sh # release build
191
+ ./build_rust.sh --debug # faster build for development
192
+ ```
193
+
194
+ This will install the required Rust toolchain if needed, build the binary,
195
+ and place it in `vllm/vllm-rs`.
196
+
197
+If you see an error about a wheel not being found, the wheel for your base
198
+commit and ROCm patch version might not be available. Check the available
199
+variants under `https://wheels.vllm.ai/rocm/<commit>/`. For example, ROCm 7.2.1
200
+uses the `rocm721` variant.
201
+
202
+There are more environment variables to control the behavior of Python-only
203
+build:
204
+
205
+- `VLLM_PRECOMPILED_WHEEL_LOCATION`: specify the exact wheel URL or local file
206
+ path of a pre-compiled wheel to use. All other logic to find the wheel will be
207
+ skipped.
208
+- `VLLM_PRECOMPILED_WHEEL_COMMIT`: override the full commit hash used to
209
+ download the pre-compiled wheel.
210
+- `VLLM_PRECOMPILED_WHEEL_VARIANT`: specify the ROCm variant subdirectory, e.g.,
211
+ `rocm700` or `rocm721`. If not specified, the variant is auto-detected based
212
+ on your system's ROCm version. An explicitly specified variant must match the
213
+ detected environment.
214
+
215
+You can find more information about vLLM's wheels in
216
+[Install the latest code](#install-the-latest-code).
217
+
218
+!!! note
219
+ There is a possibility that your source code may have a different commit ID
220
+ compared to the vLLM wheel, which could potentially lead to unknown errors.
221
+ It is recommended to use the same commit ID for the source code as the vLLM
222
+ wheel you have installed. Please refer to
223
+ [Install the latest code](#install-the-latest-code) for instructions on how
224
+ to install a specified wheel.
225
+
226
+#### Full build (with compilation) {#full-build}
227
+
228
!!! tip
229
- If you found that the following installation step does not work for you, please refer to [docker/Dockerfile.rocm_base](https://github.com/vllm-project/vllm/blob/main/docker/Dockerfile.rocm_base). Dockerfile is a form of installation steps.
230