NVIDIA releases gds-diag, an open-source tool to check GPUDirect Storage setups

What gds-diag does

NVIDIA GPUDirect Storage accelerates GPU storage access in on-premises and cloud environments. According to NVIDIA, it provides a data path between NVIDIA GPUs and storage targets that increases bandwidth, minimizes latency and reduces CPU and memory utilization. Configuring it, however, starts with understanding which settings and storage paths suit a given platform and workload. NVIDIA says extensive documentation exists, but users must navigate it to optimize their deployment.

The gds-diag tool was developed by the GPUDirect Storage team to simplify that work. It is a single Python script with multiple subcommands, each focused on a different diagnostic task. The tool does not change the system on its own. Each finding includes an explanation and a mitigation plan, but gds-diag will not implement the plan. That is left to the user or administrator.

Subcommands and how findings are reported

NVIDIA groups the subcommands into four categories, depending on the stage of deployment or the problem being investigated:

• End-to-end checks: all selects appropriate diagnostics for the environment and runs them in sequence. It works in bare-metal, virtual machine and container environments.
• Preparing for installation: pre-install checks GPU support and CUDA Toolkit installation, while support-matrix shows supported storage targets.
• Validating an installation: post-install checks whether GDS is installed correctly and identifies blockers, and config-audit reviews configuration files and environment variables that influence GDS behavior.
• Deep diagnostics: container-check assesses GDS support in containerd, Docker, Enroot and Kubernetes, and mount-check diagnoses a specific mount point or directory.

Most output is presented as findings grouped into sections, each with a status badge. FAIL indicates a hard blocker, WARN a potential blocker, INFO notable information, and PASS a nominal finding. PASS is shown only with the --verbose option. Reports can also be emitted as structured JSON with the --json option, which NVIDIA suggests could help when ingesting findings into another tool or archiving them.

The support-matrix subcommand is an exception and outputs a table with footnotes. The --static option shows general data, while --live incorporates information from the system as currently configured. Green items are fully supported, yellow items depend on architectural or configuration caveats, and red items are not supported.

In a demonstration, NVIDIA used config-audit with the --config option to review a candidate configuration file. The audit revealed a misspelled entry, and after the error was corrected, the tool confirmed the configuration was valid.

The optional agent skill

gds-diag is bundled with an optional agent skill that adds a natural-language interface and orchestration layer. According to NVIDIA, the skill interprets the user's intent, selects and invokes the appropriate subcommands, and coordinates multi-step diagnostic workflows. It also applies model-guided reasoning to interpret results, use relevant system context, and propose or carry out remediation.

The skill activates automatically when the gds-diag repository is opened in a coding assistant such as Claude or Codex. It can also be triggered explicitly with the /gds-diag keyword, though NVIDIA says this is not strictly necessary when asking natural-language questions about GDS. NVIDIA states that gds-diag is validated with both Claude and Codex, though it may work with other tools. The skill does not attempt to duplicate the deterministic checks already provided by the command-line tool.

Installation and requirements

gds-diag needs a Linux system with Python 3.8 or newer and has no other dependencies to install. GPUDirect Storage itself requires an NVIDIA datacenter-class GPU and NVIDIA CUDA Toolkit 12.2 or newer, but these are not dependencies of gds-diag. The tool is distributed as part of the NVIDIA Magnum IO GitHub repository and is installed by cloning it with git clone https://github.com/NVIDIA/MagnumIO.git.

Users can choose between two usage models. The command-line tool offers what NVIDIA calls a deterministic, minimal-dependency path. The AI agent mode is described as the most intuitive and flexible option while retaining the determinism of the underlying tool, and NVIDIA recommends it where available.

What it means for administrators

For teams deploying GDS, gds-diag offers a single place to check readiness before installation, verify it afterward and investigate container or mount-point problems. Because it reports issues and mitigation plans without modifying the system, administrators keep control over changes. The JSON output and the agent skill give two further routes: feeding results into other tooling, or working through diagnostics in plain language.