Текст и данные · Инструкция
Как настроить CUDA в WSL 2 с NVIDIA
Как настроить CUDA в WSL 2 с NVIDIA — ключевой принцип в том, что графический драйвер устанавливается в Windows, а.
Короткий ответ
Настройка NVIDIA CUDA в WSL 2: Windows-драйвер, wsl --update, nvidia-smi, CUDA Toolkit, проверка nvcc и типовые ошибки установки.
Что должно быть готово до установки CUDA
Начните с проверки, что дистрибутив действительно работает как WSL 2: `wsl -l -v` должен показывать версию 2. Затем обновите сам WSL командой `wsl --update` и перезапустите его. На стороне Windows нужен актуальный драйвер NVIDIA с поддержкой WSL. Только после этого имеет смысл настраивать Linux-пакеты. Смысл такого порядка в том, что CUDA-доступ к GPU приходит из Windows-драйвера; если пытаться «чинить» отсутствие GPU установкой обычного Linux display driver внутри Ubuntu, можно получить конфликт пакетов и потерять рабочую интеграцию. NVIDIA отдельно подчёркивает: Linux-драйвер GPU внутри WSL устанавливать не следует.
Важно: Самая опасная ошибка — поставить в Ubuntu метапакет, который тянет Linux-драйвер NVIDIA. Для WSL нужен toolkit без замены драйвера, предоставляемого Windows.
Базовая последовательность настройки
- 1. В Windows обновите драйвер NVIDIA до версии, которую текущая документация NVIDIA рекомендует для WSL. 2. В PowerShell выполните `wsl --update`, затем `wsl --shutdown`. 3. Убедитесь командой `wsl -l -v`, что рабочий дистрибутив использует WSL 2. 4. Запустите Linux и проверьте `nvidia-smi`. В WSL набор функций этой утилиты может быть ограничен, но GPU должен определяться. 5. Откройте актуальную страницу CUDA Downloads у NVIDIA и выберите вариант для WSL/Ubuntu. Устанавливайте CUDA Toolkit, не Linux display driver. 6. После установки проверьте наличие `nvcc --version`, если вам нужен компилятор, и запустите тест из вашего фреймворка или CUDA sample. 7. Зафиксируйте версии Windows-драйвера, WSL и toolkit — это сильно упрощает диагностику.
Совет: Проверка `nvidia-smi` до установки toolkit отделяет проблему драйвера/WSL от проблемы пользовательских CUDA-пакетов.
Почему nvidia-smi и nvcc отвечают на разные вопросы
`nvidia-smi` проверяет видимость GPU и часть возможностей драйвера, а `nvcc` относится к CUDA Toolkit и нужен прежде всего для компиляции CUDA-кода. Поэтому ситуация «nvidia-smi работает, а nvcc не найден» часто означает не поломку GPU, а отсутствие toolkit или неправильно настроенный PATH. Обратная ситуация, когда toolkit установлен, но GPU не виден, обычно заставляет вернуться к Windows-драйверу и версии WSL. Для готовых библиотек машинного обучения компилятор может вообще не требоваться, если пакет поставляется с нужными runtime-компонентами. Не устанавливайте дополнительные пакеты только ради того, чтобы все диагностические команды существовали: сначала определите, нужен ли вам запуск готовых CUDA-приложений или локальная компиляция.
Где должен находиться каждый компонент
- NVIDIA GPU driver | Windows | Даёт WSL доступ к GPU; Linux-драйвер внутри WSL не нужен
- WSL 2 и его ядро | Windows/WSL | Обеспечивают виртуализированную Linux-среду
- CUDA Toolkit | Linux-дистрибутив WSL | Компилятор и пользовательские инструменты для разработки
- PyTorch/TensorFlow/другой фреймворк | Linux-дистрибутив WSL | Устанавливается по инструкции самого проекта с совместимой CUDA-веткой
Предупреждение: Не смешивайте инструкции для «обычной Ubuntu на железе» и Ubuntu внутри WSL 2: схема драйверов у них различается.
Типовые сбои после установки
Если `nvidia-smi` не запускается, сначала обновите Windows-драйвер и WSL, затем полностью остановите WSL. Если `nvcc` отсутствует, проверьте, установлен ли именно toolkit и добавлен ли его bin-каталог в PATH согласно инструкции выбранной версии. Если фреймворк не видит GPU при рабочем `nvidia-smi`, сравните требования конкретной версии фреймворка с установленными runtime-библиотеками: конфликт часто находится уже выше слоя WSL. Не копируйте случайные команды добавления репозиториев из старых статей — имена пакетов и ключи репозиториев меняются. Для воспроизводимости используйте только текущую страницу CUDA Downloads и документацию фреймворка, а после обновлений меняйте один слой за раз.
Перед тем как искать сложную причину
- дистрибутив работает как WSL 2
- `wsl --update` выполнен
- Windows-драйвер NVIDIA актуален
- GPU виден из WSL через `nvidia-smi`
- внутри WSL не устанавливался отдельный Linux display driver
- toolkit выбран по актуальной инструкции NVIDIA
- версии фреймворка и CUDA совместимы
Как обновлять CUDA-стек без несовместимых слоёв
При обновлении GPU-среды меняйте по одному слою и фиксируйте версии Windows-драйвера, WSL, CUDA Toolkit и фреймворка, который реально использует CUDA. Это помогает отличить проблему драйвера от несовместимой версии PyTorch, TensorFlow, компилятора или пользовательской библиотеки. Сначала подтвердите доступ к GPU из WSL, затем проверьте инструментальную цепочку `nvcc` только если она нужна для сборки собственного CUDA-кода; наличие `nvidia-smi` само по себе не доказывает, что конкретное приложение использует GPU. Для воспроизводимой среды полезно хранить версии Python-пакетов или контейнерного образа отдельно от системного CUDA Toolkit. Не устанавливайте Linux display driver внутри WSL «для обновления»: NVIDIA отдельно предупреждает, что драйвер предоставляет Windows. После изменения версии запустите короткий вычислительный тест вашего проекта и сравните устройство, память и фактическое время работы, а не только успешный импорт библиотеки.
Минимальный тест CUDA после установки
Проверку лучше разделить на три уровня. Сначала убедитесь, что Windows-драйвер установлен и WSL видит GPU: запустите внутри дистрибутива `nvidia-smi`. Затем проверьте наличие инструментария разработки командой `nvcc --version`, если вы устанавливали CUDA Toolkit. Наконец, выполните небольшой тест в том фреймворке, который реально нужен — например, запрос доступности CUDA из вашей Python-библиотеки. Эти проверки отвечают на разные вопросы: `nvidia-smi` не доказывает, что компилятор `nvcc` установлен, а наличие `nvcc` не гарантирует совместимость конкретного пакета машинного обучения с выбранной версией CUDA. Если после обновления что-то сломалось, зафиксируйте версии Windows-драйвера, WSL, toolkit и фреймворка до дальнейших изменений. Ключевое ограничение NVIDIA для WSL остаётся тем же: Linux-драйвер NVIDIA внутри WSL ставить не нужно, потому что GPU-драйвер предоставляет Windows. Для toolkit используйте вариант установки, предназначенный для WSL/Ubuntu, и избегайте метапакетов, которые пытаются поставить Linux display driver.
Что учитывать
`nvidia-smi` проверяет видимость GPU и часть возможностей драйвера, а `nvcc` относится к CUDA Toolkit и нужен прежде всего для компиляции CUDA-кода. Поэтому ситуация «nvidia-smi работает, а nvcc не найден» часто означает не поломку GPU, а отсутствие toolkit или неправильно настроенный PATH. Обратная ситуация, когда toolkit установлен, но GPU не виден, обычно заставляет вернуться к Windows-драйверу и версии WSL. Для готовых библиотек машинного обучения компилятор может вообще не требоваться…
Источники и проверка
Инструкция составлена редакцией N1RO на 2026-09-20. Перед действием сверьте актуальные условия на официальном сайте сервиса или производителя.