Install the AMD SMI library and CLI tool

Install the AMD SMI library and CLI tool#

This page describes the system requirements for AMD SMI and explains how to install the AMD SMI library, Python interface, and amd-smi CLI on Linux.

Supported platforms#

AMD SMI supports:

AMD GPUs on Linux bare metal systems
AMD GPUs in Linux virtual machine guests
AMD EPYC™ CPUs through the esmi_ib_library

For AMD SMI on Linux SR-IOV hosts, refer to the AMD SMI for Virtualization documentation.

AMD SMI library runs on AMD ROCm supported platforms. Refer to AMD hardware support for more information.

Requirements#

Before installing AMD SMI, make sure your system meets the following requirements.

Driver requirements#

To run AMD SMI, the following components need to be installed on your system:

The amdgpu-dkms driver
- For current amdgpu driver installation instructions, see the AMD GPU Driver (amdgpu) documentation.
  Note
  
  ROCm releases claim support for a range of amdgpu driver versions. Because AMD SMI gets GPU telemetry and management data directly from the amdgpu kernel driver, version mismatches in either direction can affect which metrics and controls are available:
  - If the amdgpu driver is older than your AMD SMI release expects, some features might be unavailable, causing some fields to read N/A.
  - If the amdgpu driver is newer than AMD SMI expects, AMD SMI might not recognize new data formats (for example, newer gpu_metrics versions) and can report N/A for affected fields.
  To maximize compatibility, we recommend using the latest amdgpu driver version that matches your AMD SMI or ROCm release. See About N/A values for more information.
The amd_hsmp or hsmp_acpi driver
- See amd_hsmp for more information.

Also confirm that your Linux kernel version matches the system requirements described in Operating system support.

Interface prerequisites#

The following prerequisites apply to the AMD SMI library interfaces:

Python interface and amd-smi CLI:
- Python 3.6.8 or later
- 64-bit Python
Go interface:
- Go 1.20 or later

Note

During the driver installation process on Azure Linux 3, you might encounter the ModuleNotFoundError: No module named 'more_itertools' warning. This warning is a result of the reintroduction of python3-wheel and python3-setuptools dependencies in the CMake of AMD SMI, which requires more_itertools to build these Python libraries. This issue will be fixed in a future ROCm release. As a workaround, use the following command before installation:

sudo python3 -m pip install more_itertools

Install the ROCm Core SDK#

AMD SMI is included with most installations of the ROCm Core SDK on Linux.

For instructions, see Install AMD ROCm. Use the selector panel on that page to view instructions appropriate for your system environment.

Install AMD SMI standalone on Linux#

Alternatively, if you want to install AMD SMI without additional ROCm libraries and tools, install the amdrocm-amdsmi package. This includes AMD SMI and ROCm system dependencies.

Complete the ROCm installation prerequisites to install dependencies and configure GPU access permissions.
Install the AMD SMI package that matches your desired ROCm version. Package names use the following format:
```
amdrocm-amdsmi<rocm_version>
```
<rocm_version> represents the ROCm Core SDK version to install. Omit this suffix to install the latest available version.

For example, to install the latest ROCm AMD SMI release for supported GPU architectures:
Debian-based distros
sudo apt install amdrocm-amdsmi
RHEL-based distros
sudo dnf install amdrocm-amdsmi
SLES
sudo zypper install amdrocm-amdsmi
Prepend the amd-smi binary to your PATH, it is not on PATH by default. Replace <major> and <minor> with the appropriate ROCm version.
```
export PATH="/opt/rocm/core-<major>.<minor>/bin${PATH:+:${PATH}}"
```
To persist this across shells, append the line to your ~/.bashrc (or equivalent shell config).
Verify your installation.
```
amd-smi version
```

Install a nightly build#

Nightly builds of the ROCm Core SDK (including AMD SMI) are published by TheRock to a unified pip index.

Create and activate a Python virtual environment (recommended):
```
python3 -m venv .venv
source .venv/bin/activate
```
Install ROCm with the device extra matching your GPU. For example, for gfx942 (MI300X / MI325X):
```
pip install --index-url https://rocm.nightlies.amd.com/whl-multi-arch/ \
    "rocm[libraries,device-gfx942]"
```
For the full list of device-* extras and other release options, see TheRock RELEASES.md.
Verify your installation:
```
amd-smi version
```

Optional and advanced installation#

Use these optional procedures for CLI autocompletion and advanced setups, such as systems with multiple ROCm instances.

Enable CLI autocompletion#

The amd-smi CLI application supports autocompletion. If argcomplete is not installed and enabled already, do so using the following commands.

python3 -m pip install argcomplete
activate-global-python-argcomplete --user
# restart shell to enable

Install the Python library for multiple ROCm instances#

If multiple ROCm versions are installed and you are not using pyenv, uninstall previous versions of AMD SMI before installing the desired version from your ROCm instance.

Manually install the Python library#

Multiple ROCm installations may cause amd-smi failures. Installing multiple versions of ROCm on the same system can result in the amd-smi CLI not functioning correctly.

Starting with ROCm 7.14, the amd-smi-lib rpm/deb package no longer runs pip install during postinst — it installs the amdsmi Python package directly into the system Python’s site-packages as part of the package payload. Removing the package removes those files; only a legacy (pre-7.14) pip-registered install needs to be uninstalled manually.

Remove previous AMD SMI installations.

# Legacy: pre-7.14 system packages and any user pip install
python3 -m pip list | grep amd
python3 -m pip uninstall amdsmi

# Modern: 7.14+ system package, remove it with your package manager
sudo apt remove amd-smi-lib   # or: sudo dnf remove amd-smi-lib

Install the AMD SMI Python library. Pick one of the two paths:
- System package (recommended when you want the rpm/deb to manage the install). Install or reinstall amd-smi-lib from your target ROCm instance; the package installs the wrapper into the system Python’s site-packages so import amdsmi resolves it directly.
- Pip wheel (recommended for venvs, containers, or when ROCm is not installed on the host but the amdgpu kernel driver is present):
```
python3 -m pip install amdsmi
```
  The wheel ships its own SONAME-renamed libamd_smi_python.so next to the wrapper, so it does not depend on /opt/rocm being present.
See py-interface/README.md in the source tree, or Packaging and install paths for the full install-paths matrix, coexistence rules, and the AMDSMI_LIB_OVERRIDE override.

Note: sudo may be required for the system-package path. For pip, use --break-system-packages only if installing into a non-venv Python that PEP 668 has marked externally managed.

You should now have the AMD SMI Python library in your Python path:

~$ python3
Python 3.8.10 (default, May 26 2023, 14:05:08)
[GCC 9.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import amdsmi
>>>