Как установить и настроить NVIDIA CUDA Toolkit

Иван Корнев·6 июля 2026·⏱4 мин

Для успешной установки NVIDIA CUDA Toolkit необходимо скачать инсталлятор с официального сайта, выбрать версию, совместимую с вашим графическим процессором и драйверами, и корректно прописать пути к исполняемым файлам в системных переменных. Ключевой этап — проверка работы компилятора через команду nvcc --version и статуса GPU через nvidia-smi. В этом руководстве разобраны нюансы установки на Windows и Linux, а также методы диагностики типовых ошибок.

Оглавление

  1. Подготовка: выбор версии и требования
  2. Инструкция для Windows
  3. Инструкция для Linux (Ubuntu/Debian)
  4. Ситуация с macOS
  5. Проверка и диагностика
  6. Частые ошибки и решения
  7. FAQ

Подготовка: выбор версии и требования

Перед загрузкой дистрибутива критически важно определить совместимость компонентов. Ошибка на этом этапе приводит к неработоспособности среды разработки.

  • Версия CUDA. Выбирайте ту, которую поддерживает ваш стек машинного обучения (PyTorch, TensorFlow). Например, если библиотека требует CUDA 11.8, установка версии 12.4 без дополнительной настройки не позволит запустить код.
  • Драйвер NVIDIA. Драйвер должен быть новее или равен минимальной требуемой версии для выбранного Toolkit. Таблицу совместимости всегда можно найти в документации NVIDIA.
  • Операционная система. Убедитесь, что ваша ОС поддерживается. Для Linux проверьте наличие заголовков ядра (linux-headers), необходимых для сборки модулей драйвера.

Инструкция для Windows

На Windows установка наиболее автоматизирована, но требует внимания к путям интеграции.

  1. Скачайте установщик (exe) с сайта NVIDIA Developer. Рекомендуется выбирать локальный инсталлятор, чтобы иметь файл под рукой для переустановки.
  2. Запустите файл от имени администратора.
  3. Выберите тип установки Custom (Выборочная). Это позволит отключить установку драйвера GeForce Experience, если он вам не нужен, и четко контролировать компоненты.
  4. Отметьте галочками CUDA, Driver (если нужна обновление) и опционально Nsight Systems/Compute для профилирования.
  5. Завершите установку и перезагрузите компьютер.

Если вы разрабатываете в WSL2 (Windows Subsystem for Linux), не устанавливайте CUDA Toolkit внутри Linux-окружения вручную. Достаточно установить драйвер NVIDIA с поддержкой CUDA в основной Windows-системе. WSL2 автоматически пробросит доступ к GPU.

Инструкция для Linux (Ubuntu/Debian)

На Linux предпочтительнее использовать пакетный менеджер, так как это упрощает будущие обновления и удаление.

Шаг 1: Подготовка системы

Установите необходимые зависимости и заголовки ядра:

sudo apt update
sudo apt install -y build-essential dkms linux-headers-$(uname -r)

Шаг 2: Добавление репозитория NVIDIA

Загрузите ключ и добавьте репозиторий для вашей версии Ubuntu (пример для Ubuntu 22.04):

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update

Шаг 3: Установка Toolkit

Установите мета-пакет нужной версии. Например, для CUDA 12.4:

sudo apt install -y cuda-toolkit-12-4

Шаг 4: Настройка переменных окружения

Добавьте пути в файл конфигурации оболочки (~/.bashrc или ~/.zshrc):

export PATH=/usr/local/cuda-12.4/bin${PATH:+:${PATH}}
export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

Примените изменения командой source ~/.bashrc.

Ситуация с macOS

Поддержка нативной CUDA на macOS прекращена несколько лет назад. Современные Mac на чипах Apple Silicon (M1/M2/M3) используют архитектуру Metal и фреймворк MPS (Metal Performance Shaders) для ускорения вычислений.

Если вам критически необходима именно CUDA:

  • Используйте облачные серверы с GPU NVIDIA.
  • Запустите Linux в виртуальной машине с пробросом внешней видеокарты (сложно и требует специфического железа).
  • Для большинства задач ML на Mac сейчас оптимально использовать PyTorch с бэкендом MPS.

Проверка и диагностика

После установки выполните две ключевые проверки в терминале.

  1. Проверка компилятора:
    nvcc --version
    ```
    Команда должна вывести номер версии релиза. Если получено сообщение "command not found", значит, переменная `PATH` настроена неверно.

2.  **Проверка драйвера и GPU:**
    
```bash
    nvidia-smi
    ```
    В таблице справа сверху отображается версия драйвера и максимальная поддерживаемая им версия CUDA Runtime API. Убедитесь, что установленный Toolkit не превышает это значение.

## Частые ошибки и решения

<div class="table-container"><table style="border-collapse: collapse; width: 100%; margin: 16px 0;"><thead><tr><th style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; background: #f9fafb; font-weight: 600;">Проблема</th><th style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; background: #f9fafb; font-weight: 600;">Причина</th><th style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; background: #f9fafb; font-weight: 600;">Решение</th></tr></thead><tbody><tr><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">nvcc: command not found</code></td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Пути не добавлены в环境变量</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Проверьте <code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">.bashrc</code> или системные переменные Windows. Перезапустите терминал.</td></tr><tr><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Ошибка совместимости при запуске Python-скрипта</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Версия CUDA в системе не совпадает с ожидаемой библиотекой</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Установите точную версию CUDA, требуемую фреймворком, или используйте Conda-пакеты, которые поставляют свои библиотеки runtime.</td></tr><tr><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">NVIDIA-SMI has failed because it couldn&#39;t communicate with the NVIDIA driver</code></td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Драйвер не загружен или конфликтует с ядром</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Перезагрузите ПК. В Linux проверьте статус модуля <code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">nvidia</code> через <code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">lsmod</code>. Возможно, требуется отключение Secure Boot.</td></tr><tr><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Конфликт версий после обновления</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">В системе остались файлы от старой версии</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">При установке новой версии поверх старой на Linux используйте <code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">apt purge</code> для полного удаления старых пакетов перед новой установкой.</td></tr></tbody></table></div>

Не рекомендуется устанавливать несколько мажорных версий CUDA Toolkit в системные директории параллельно без четкого понимания управления символическими ссылками (/usr/local/cuda). Это часто приводит к ошибкам линковки.

FAQ

Нужно ли переустанавливать драйвер при обновлении CUDA Toolkit? Не всегда. Если текущий драйвер поддерживает новую версию CUDA (проверьте таблицу совместимости NVIDIA), можно обновить только Toolkit. Однако для стабильности часто рекомендуют обновлять и драйвер до последней версии.

Что лучше: Installer (runfile) или Package Manager (deb/rpm)? Package Manager предпочтительнее для Linux, так как интегрируется с системой обновлений. Runfile полезен, если нужно установить конкретную версию в изолированную директорию без влияния на системные пакеты.

Как проверить, видит ли PyTorch мою CUDA? Запустите Python и выполните:

import torch
print(torch.cuda.is_available())
print(torch.version.cuda)

Если вывод True и версия совпадает с ожидаемой, настройка прошла успешно.