Skip to content

cuda-install

Get step-by-step CUDA Toolkit installation instructions tailored to your platform.

Overview

The cuda-install command automatically:

  1. Detects your platform (OS, distribution, version, architecture, WSL2)
  2. Analyzes your GPU driver to determine the best CUDA version
  3. Provides copy-paste installation commands specific to your system
  4. Includes post-installation setup (environment variables, verification)
  5. Shows official download links for manual installation if needed

Usage

env-doctor cuda-install

This will: - Check your NVIDIA driver version - Recommend the best CUDA Toolkit version - Show platform-specific installation steps

Install specific CUDA version

env-doctor cuda-install 12.8
env-doctor cuda-install 12.4
env-doctor cuda-install 12.1
env-doctor cuda-install 11.8

Get JSON output (for automation/CI)

env-doctor cuda-install --json
env-doctor cuda-install 12.6 --json

Returns structured JSON with platform info, recommended version, and install steps for machine processing.

Example Output

Linux (Ubuntu)

$ env-doctor cuda-install

============================================================
CUDA TOOLKIT INSTALLATION GUIDE
============================================================

Detected Platform:
    Linux (ubuntu 22.04, x86_64)

Driver: 535.146.02 (supports up to CUDA 12.2)
Recommended CUDA Toolkit: 12.1

============================================================
Ubuntu 22.04 (x86_64) - Network Install
============================================================

Installation Steps:
------------------------------------------------------------
    1. wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
    2. sudo dpkg -i cuda-keyring_1.1-1_all.deb
    3. sudo apt-get update
    4. sudo apt-get -y install cuda-toolkit-12-1

Post-Installation Setup:
------------------------------------------------------------
    export PATH=/usr/local/cuda-12.1/bin${PATH:+:${PATH}}
    export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

    TIP: Add the above exports to ~/.bashrc or ~/.zshrc

Verify Installation:
------------------------------------------------------------
    nvcc --version

Official Download Page:
    https://developer.nvidia.com/cuda-12-1-0-download-archive

============================================================
After installation, run 'env-doctor check' to verify.
============================================================

WSL2 (Special Instructions)

$ env-doctor cuda-install

============================================================
CUDA TOOLKIT INSTALLATION GUIDE
============================================================

Detected Platform:
    WSL2 (ubuntu 22.04)

Driver: 560.35.03 (supports up to CUDA 12.6)
Recommended CUDA Toolkit: 12.6

============================================================
WSL2 (Ubuntu) - DO NOT install driver inside WSL
============================================================

Prerequisites:
    - Ensure Windows NVIDIA driver >= 560.xx is installed on the HOST
    - DO NOT install nvidia-driver packages inside WSL2

Installation Steps:
------------------------------------------------------------
    1. wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
    2. sudo dpkg -i cuda-keyring_1.1-1_all.deb
    3. sudo apt-get update
    4. sudo apt-get -y install cuda-toolkit-12-6

Post-Installation Setup:
------------------------------------------------------------
    export PATH=/usr/local/cuda-12.6/bin${PATH:+:${PATH}}
    export LD_LIBRARY_PATH=/usr/local/cuda-12.6/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

    TIP: Add the above exports to ~/.bashrc or ~/.zshrc

Verify Installation:
------------------------------------------------------------
    nvcc --version

Notes:
    GPU driver is forwarded from Windows host. Only install the toolkit inside WSL2.

============================================================

Windows

$ env-doctor cuda-install

============================================================
CUDA TOOLKIT INSTALLATION GUIDE
============================================================

Detected Platform:
    Windows (x86_64)

Driver: 560.35.03 (supports up to CUDA 12.6)
Recommended CUDA Toolkit: 12.6

============================================================
Windows 10/11 (x86_64) - winget
============================================================

Installation Steps:
------------------------------------------------------------
    1. winget install Nvidia.CUDA --version 12.6

Post-Installation Setup:
------------------------------------------------------------
    The installer automatically adds CUDA to PATH
    Restart your terminal/IDE after installation

Verify Installation:
------------------------------------------------------------
    nvcc --version

Notes:
    If winget is not available, download manually from the official page.

Official Download Page:
    https://developer.nvidia.com/cuda-12-6-0-download-archive

============================================================

New in 0.2.6: Windows now uses winget (Windows Package Manager) for automated installation instead of manual GUI steps.

Supported Platforms

Linux Distributions

Distribution Versions Package Manager
Ubuntu 18.04, 20.04, 22.04, 24.04 apt (deb)
Debian 11, 12 apt (deb)
RHEL / Rocky / AlmaLinux 7, 8, 9 dnf/yum (rpm)
Fedora 39+ dnf (rpm)
WSL2 Ubuntu All versions apt (deb)

Other Platforms

Platform Installation Method
Windows 10/11 winget (Windows Package Manager)
macOS Not supported (CUDA deprecated)
Conda (any platform) conda install cuda-toolkit

New in 0.2.6: Windows now uses winget for automated installation instead of manual GUI steps.

CUDA Versions Supported

The tool provides installation instructions for 9 CUDA versions:

CUDA 12.x (Latest) - CUDA 12.8 (Latest, requires driver >= 570.xx) - CUDA 12.6 (Latest stable, requires driver >= 560.xx) - CUDA 12.5 (requires driver >= 555.xx) - CUDA 12.4 (TensorFlow 2.16+, requires driver >= 550.xx) - CUDA 12.2 (requires driver >= 535.xx) - CUDA 12.1 (PyTorch 2.x sweet spot, requires driver >= 530.xx) - CUDA 12.0 (First CUDA 12 release, requires driver >= 525.xx)

CUDA 11.x (Legacy) - CUDA 11.8 (Latest CUDA 11, requires driver >= 520.xx) - CUDA 11.7 (requires driver >= 515.xx)

Version Recommendation Logic

The tool automatically recommends the best CUDA version based on:

  1. Your GPU driver - Maps driver version to max supported CUDA
  2. Forward compatibility - Recommends latest stable CUDA your driver supports
  3. Library compatibility - Considers PyTorch/TensorFlow requirements

Example Mappings (Updated in 0.2.6):

Driver Version Max CUDA Recommended Toolkit
570.xx+ 12.8 CUDA 12.8
560.xx 12.6 CUDA 12.6
555.xx 12.5 CUDA 12.5
550.xx 12.4 CUDA 12.4
535.xx 12.2 CUDA 12.2
530.xx 12.1 CUDA 12.1
525.xx 12.0 CUDA 12.0
520.xx 11.8 CUDA 11.8
515.xx 11.7 CUDA 11.7

Common Use Cases

Case 1: New Machine Setup

# 1. Check current state
env-doctor check

# 2. Get installation instructions
env-doctor cuda-install

# 3. Follow the steps shown

# 4. Verify installation
env-doctor check

Case 2: Upgrade CUDA for PyTorch Compatibility

# 1. Check current versions
env-doctor check

# 2. Get instructions for specific version
env-doctor cuda-install 12.4

# 3. Install and verify
env-doctor check

Case 3: WSL2 GPU Setup

# Inside WSL2:
# 1. Check if driver is forwarded
env-doctor check

# 2. Get WSL2-specific instructions
env-doctor cuda-install

# 3. Follow WSL2 prerequisites carefully (don't install driver in WSL!)

JSON Output for Automation

Get structured JSON output for integration with CI/CD pipelines:

env-doctor cuda-install --json

Response format: 

{
  "platform": {
    "os": "windows",
    "distro": "windows",
    "arch": "x86_64",
    "is_wsl2": false
  },
  "recommended_version": "12.6",
  "driver_version": "560.35.03",
  "max_cuda": "12.6",
  "install_info": {
    "method": "winget",
    "label": "Windows 10/11 (x86_64) - winget",
    "steps": ["winget install Nvidia.CUDA --version 12.6"],
    "post_install": ["The installer automatically adds CUDA to PATH"],
    "verify": "nvcc --version",
    "download_page": "https://developer.nvidia.com/cuda-12-6-0-download-archive"
  }
}

New in 0.2.6: --json flag allows machine-readable output for automation, testing, and CI/CD integration.

Post-Installation

After installing CUDA Toolkit:

  1. Verify installation: 

    nvcc --version

  2. Run full diagnostic: 

    env-doctor check

  3. Install Python libraries: 

    env-doctor install torch

Troubleshooting

"No NVIDIA driver detected"

Install the NVIDIA driver first: - Linux: Use your distribution's package manager or NVIDIA's .run installer - Windows: Download from NVIDIA Drivers - WSL2: Install driver on Windows host, not in WSL2

"No specific instructions for your platform"

The tool will show: - List of available platforms for your CUDA version - Generic download link to NVIDIA's website - Conda installation as universal fallback

You can also specify a different CUDA version that might have your platform: 

env-doctor cuda-install 12.1

Multiple CUDA Installations

If you already have CUDA installed: - The new installation will be in a versioned directory (e.g., /usr/local/cuda-12.4) - Update CUDA_HOME and PATH to point to the version you want - Use env-doctor cuda-info to see all installations

Integration with Other Commands

The cuda-install command works seamlessly with:

  • env-doctor check - See what's currently installed
  • env-doctor cuda-info - Detailed analysis of CUDA installations
  • env-doctor install <lib> - Get library install commands after CUDA is set up

See Also