NVIDIA GPUDirect Storage (GDS) accelerates GPU storage access in on-premises and cloud environments. It provides a robust, portable, and efficient data path between NVIDIA GPUs and storage targets to increase bandwidth, minimize latency, and reduce CPU and memory utilization across a broad range of platforms, application frameworks, and workload patterns.
Configuring NVIDIA GPUDirect Storage starts with understanding your environment. Which settings and storage paths are appropriate for your platform and workload? Extensive documentation describes how to configure and troubleshoot supported architectures and storage solutions, but you must navigate this information and optimize your deployment.
The gds-diag tool was developed by the GPUDirect Storage team to simplify optimization and configuration of GPUDirect Storage. gds-diag is a simple, open-source command-line utility that assesses environments, identifies problems, and suggests improvements to help you make the most of your GDS deployment.
It is also bundled with an optional agent skill that adds a natural-language interface and orchestration layer. The skill interprets your intent, selects and invokes the appropriate subcommands, and coordinates multi-step diagnostic workflows. Beyond command selection and routing, the skill extends gds-diag with model-guided reasoning. It can interpret diagnostic results, apply relevant system context, and propose or carry out appropriate remediation.
This post shows you how to get started with gds-diag using either the command-line interface or the agent skill.
Download and installation
To use gds-diag, you need a Linux system with Python 3.8 or newer. GPUDirect Storage requires an NVIDIA datacenter-class GPU and NVIDIA CUDA Toolkit 12.2 or newer, but these are not dependencies of gds-diag itself.
gds-diag is distributed as part of the NVIDIA Magnum IO GitHub repository with no other dependencies to install. Clone the repository on the machine where you plan to run it with git clone https://github.com/NVIDIA/MagnumIO.git and select one of the following usage models:
- Command-line tool: This provides a deterministic, minimal-dependency path to diagnose GDS deployments. Go to the
gds-diagdirectory, rungds-diag.py --help, and follow the Command-line usage guidance.
- AI agent: This provides the most intuitive, flexible, interactive, natural-language mechanism to diagnose GDS deployments while still retaining the reliable determinism of the underlying command-line tool. Open the
gds-diagdirectory in your preferred AI coding assistant and follow the Agent skill usage guidance.
Quick tip: The AI agent mode is recommended if this option is available in your environment. gds-diag is validated with both Claude and Codex, though it may work with other tools as well. |
|---|
Command-line usage
The gds-diag command-line tool is a single Python script with multiple subcommands to focus on different diagnostic tasks. You can browse available subcommands by running ./gds-diag.py --help.
For more information about a specific subcommand, run ./gds-diag.py <subcommand> --help.
Quick tip: Not sure where to start? Just run ./gds-diag.py all /path/to/check, and gds-diag will automatically run a complete sequence of diagnostics for that path. This works in bare-metal, virtual machine, and container environments. |
|---|
Figure 2 groups the available subcommands into four categories.
Choose a diagnostic category based on your stage of deployment or the problem you need to investigate.
- End-to-end checks: Use
allto automatically select appropriate diagnostics for your environment and run them in sequence. - Preparing for installation: Use
pre-installto check GPU support and CUDA Toolkit installation. Usesupport-matrixto view supported storage targets and plan your deployment. - Validating an installation: Use
post-installto check whether GDS is installed correctly and identify blockers. Useconfig-auditto review configuration files and environment variables that influence GDS behavior. - Deep diagnostics: Use
container-checkto assess GDS support in container environments, including containerd, Docker, Enroot, and Kubernetes. Usemount-checkto diagnose a specific mount point or directory.
The anatomy of a gds-diag finding
The output of most gds-diag subcommands is presented as a set of findings grouped into sections, as Figure 3 shows.
Each finding and each section has a status badge.
- “FAIL” indicates a hard blocker.
- “WARN” indicates a potential blocker.
- “INFO” communicates notable information.
- “PASS” indicates a nominal finding and is shown only when you use the
--verboseoption.
Each finding includes an explanation followed by a mitigation plan. gds-diag will not implement the mitigation plan or otherwise modify the system on its own. Its role is to identify problems and optimization opportunities and help you or your administrator make improvements. Multiple sections (and findings within those sections) may be shown.
Quick tip: You can also emit all diagnostic reports as structured JSON data with the --json command-line option. This could be useful if you plan to ingest findings into another tool or archive them for future reference. |
|---|
Most subcommands follow the same structure. The gds-diag.py support-matrix command is a notable exception: it emits output in the form of a table with footnotes. This subcommand shows which platform combinations GDS supports.
Use the --static option to present general data (shown in Figure 4) or the --live option to incorporate information from the system as presently configured.
Items marked in green are fully supported, items marked in yellow are supported depending on architectural or configuration caveats, and items marked in red are not supported.
Quick tip: Most distributed storage vendors elect to present their file systems as nfs or nfs4 at the Linux operating system level, so this row of the support matrix corresponds to a broad range of product support. |
|---|
Command-line demo
To demonstrate, consider preparing a new or modified GDS configuration file for production deployment. The config-audit subcommand is an ideal choice for this scenario. If called with no arguments, it will audit the current effective configuration, including both static configuration files and dynamic environment variable modifiers. The following example uses the --config option to specify a candidate configuration to review.
The configuration audit reveals a misspelled entry in the configuration file. After you correct the error, config-audit confirms that the configuration is valid and provides additional informational hints.
Agent skill usage
The gds-diag agent skill activates automatically when you open the gds-diag repository using a coding assistant such as Claude or Codex.
Quick tip: You can explicitly activate gds-diag using the /gds-diag keyword in your coding assistant, but this isn’t strictly necessary. It will automatically choose it as the appropriate skill to use if you ask natural language questions about GDS. |
|---|
The skill does not attempt to duplicate deterministic checks that are already provided by the gds-diag command-line tool. Instead, its primary role is to aid in routing between gds-diag subcommands and interpreting their output. The following are a few examples of queries you could pose using the skill:
- Is this system eligible to use GDS?
- Is it available for
/mnt/data? - How do I configure GDS optimally to access
/mnt/data? - What configuration files are being used by GDS?
- Do any configuration parameters need to be updated?
- Which NVMe device has the best locality to GPU3?
Agents are a capability multiplier for gds-diag; you can ask follow-up questions or even ask the agent to implement mitigations on your behalf.
Agent skill demo
Figure 6 shows how to combine the gds-diag agent skill with a model’s inherent reasoning to diagnose a container configuration problem. This example uses Anthropic Claude Code CLI.
In this case, the agent inspects the shell script used to launch the container and determines the best gds-diag tool to use to investigate the problem. It then offers the option to modify the script in response to its findings and confirms the solution. Note that the coding assistant will honor your local settings and site policies to determine which actions require confirmation.
Get started
Use gds-diag as your first diagnostic tool when investigating GPUDirect Storage configuration and optimization. Its modular design provides a foundation for additional diagnostics, such as checks for network transports, object storage systems, and application frameworks.
Have a diagnostic check or file system you would like to contribute? Community contributions are welcome and strongly encouraged. Both the source code and the agent skill are published under open-source licenses (Apache 2.0 and Creative Commons Attribution 4.0 International). See the contributor guidelines to get started.
