Диагностика проблем

Собранный в одном месте разбор того, что чаще всего идёт не так при установке. Если вашей ошибки здесь нет — в конце главы написано, что собрать и куда прислать, чтобы вам помогли быстро.

Сначала — минутная проверка

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

Windows (в PowerShell)

wsl --list --verbose        # WSL стоит, версия 2, дистрибутив запущен?
wsl --status                # версия ядра и дистрибутив по умолчанию

Дальше — уже внутри Ubuntu, команды из соседней вкладки.

Linux и macOS

uv --version                            # uv установлен и виден в PATH?
uv run mojo --version                   # компилятор ставится и запускается?
ldd --version | head -1                 # (Linux) glibc 2.34 или новее?
echo 'def main(): print("ok")' > /tmp/t.mojo && uv run mojo /tmp/t.mojo

Если всё в порядке, последняя команда напечатает

ok

Ниже — разбор по симптомам.

Ошибки WSL

Error: 0x80370102 The virtual machine could not be started because a required feature is not installed

Что это значит

Windows не может запустить виртуальную машину: не включён компонент «Платформа виртуальной машины», отключена виртуализация в BIOS/UEFI либо процессор не поддерживает нужные расширения.

Как исправить

По порядку, в PowerShell от администратора:

1. Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
2. Перезагрузиться, зайти в BIOS/UEFI (Del или F2 при включении) и включить Intel VT-x, AMD-V или SVM Mode.
3. Проверить гипервизор: bcdedit /enum | findstr -i hypervisorlaunchtype. Если Off — включить: bcdedit /set hypervisorlaunchtype Auto и перезагрузиться.

WslRegisterDistribution failed with error: 0x8007019e

Что это значит

Не включён сам компонент «Подсистема Windows для Linux».

Как исправить

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux в PowerShell от администратора, затем перезагрузка.

WslRegisterDistribution failed with error: 0x80070003

Что это значит

WSL не может найти или создать файлы дистрибутива: обычно это повреждённая установка или нехватка места на диске.

Как исправить

Проверьте свободное место на системном диске. Затем удалите и поставьте дистрибутив заново: wsl --unregister Ubuntu-24.04, после чего wsl --install -d Ubuntu-24.04.

Команда --unregister удаляет все файлы внутри дистрибутива — сначала скопируйте оттуда всё нужное.

wsl : Термин «wsl» не распознан как имя командлета

Что это значит

Сборка Windows слишком старая: команды wsl --install в ней ещё нет.

Как исправить

Нужна Windows 10 версии 2004 (сборка 19041) или новее. Проверьте через winver и обновите систему.

The distribution failed to start / WSL зависает при запуске

Что это значит

Чаще всего конфликт с другим гипервизором либо повреждённое состояние после сбоя.

Как исправить

Сначала полная перезагрузка WSL: wsl --shutdown, затем запустить дистрибутив заново. Если не помогло — обновите VirtualBox (нужна 6.0+) или VMware (15.5.5+): старые версии не уживаются с гипервизором Windows.

Кончается место на диске C

Виртуальный диск WSL растёт по мере использования и по умолчанию лежит на системном диске. Два способа справиться:

Разрешить диску отдавать освободившееся место. В файле C:\Users\<ВашеИмя>\.wslconfig:

%UserProfile%.wslconfig

[experimental]
sparseVhd=true

Затем wsl --shutdown.

Перенести дистрибутив на другой диск:

wsl --shutdown
wsl --export Ubuntu-24.04 D:\wsl-backup\ubuntu.tar
wsl --unregister Ubuntu-24.04
wsl --import Ubuntu-24.04 D:\wsl\ubuntu D:\wsl-backup\ubuntu.tar

После импорта пользователь по умолчанию сбрасывается на root. Вернуть своего:

ubuntu2404.exe config --default-user вашеимя

Ошибки установки Mojo

mojo: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found

Что это значит

Слишком старая версия glibc — Mojo требует 2.34 или новее. Типично для Ubuntu 20.04, Debian 11, CentOS 7.

Как исправить

Обновить дистрибутив до Ubuntu 22.04 LTS или новее. В WSL проще всего поставить свежий дистрибутив рядом: wsl --install -d Ubuntu-24.04.

Illegal instruction (core dumped)

Что это значит

Процессор не поддерживает инструкции, на которые рассчитан компилятор: нужен уровень x86-64-v3 — Haswell и новее.

Как исправить

Проверьте набор инструкций: lscpu | grep -o -E 'avx2|bmi2|fma' | sort -u. Если avx2 нет — на этом железе Mojo не запустится, нужна удалённая машина. Та же ошибка бывает на виртуальных машинах, где гипервизор скрывает AVX2 от гостевой системы — тогда включите проброс инструкций в настройках ВМ.

mojo: command not found

Что это значит

Mojo установлен внутрь окружения проекта, а вы вызываете его напрямую, без активации окружения.

Как исправить

Запускайте uv run mojo ... из папки проекта либо активируйте окружение: source .venv/bin/activate.

uv: command not found

Что это значит

uv установлен, но его каталог не попал в PATH текущей сессии.

Как исправить

Перезапустите терминал или выполните source ~/.bashrc (для zsh — ~/.zshrc). Если не помогло, проверьте, что файл существует: ls ~/.local/bin/uv, и добавьте каталог в PATH: export PATH="$HOME/.local/bin:$PATH".

error: externally-managed-environment

Что это значит

Попытка поставить пакет в системный Python. Дистрибутивы и Homebrew такое запрещают намеренно.

Как исправить

Ставьте в проект: uv init и uv add mojo. Флаг --break-system-packages не используйте — название у него честное.

ld: cannot find -lc / cc: command not found

Что это значит

Нет системного компилятора C, а он нужен Mojo для линковки готовой программы.

Как исправить

Linux: sudo apt install build-essential. macOS: xcode-select --install.

Проблемы с VS Code

Строка состояния сообщает, что SDK не найден

Что это значит

Расширение Mojo не нашло окружение с компилятором — обычно расширение Python выбрало глобальный интерпретатор вместо проектного.

Как исправить

Python: Select Interpreter → выбрать .venv проекта → Mojo: Refresh SDK Detection. Если не помогло, укажите путь явно в .vscode/settings.json — подробности в главе Настройка VS Code.

Расширение Mojo вообще не активируется, команд Mojo нет в палитре

Что это значит

Расширение установлено не на той стороне: в Windows вместо WSL либо локально вместо удалённой сессии.

Как исправить

Откройте панель расширений: у расширения Mojo должна быть кнопка Install in WSL: Ubuntu-24.04 (или Install in SSH: ...). Если она есть — значит, оно стоит не там, где нужно.

Компиляция очень медленная

Три причины по частоте:

1. Проект лежит в /mnt/c/... — то есть в файловой системе Windows. Перенесите его в ~/projects внутри Linux: обращение к дискам Windows идёт через медленную прослойку.
2. WSL не хватает памяти. По умолчанию он берёт часть ОЗУ, и при 8 ГБ на машине компилятору может быть тесно. Настройте лимиты в .wslconfig — см. главу про WSL.
3. Антивирус проверяет каждый файл сборки. Добавьте папку проекта и виртуальный диск WSL в исключения Microsoft Defender.

Если ничего не помогло

Соберите вот это — с такими данными вам ответят с первого раза, а не после трёх уточняющих вопросов:

1. Версии:

   uv run mojo --version
   uv --version

2. Система:

   uname -a
   ldd --version | head -1

   На Windows дополнительно wsl --version в PowerShell.

3. Процессор:

   lscpu | head -20

4. Полный текст ошибки — целиком, а не последняя строка. Именно в середине обычно и написано, что произошло.

5. Минимальный пример, который воспроизводит проблему.

Куда писать:

• форум Modular — вопросы про сам язык и установку, отвечают в том числе разработчики;
• issues репозитория modular/modular — если похоже на баг компилятора;
• issues этого курса — если ошибка в тексте главы или чего-то не хватает в этом справочнике.

Ошибка, которой здесь нет

Если вы решили проблему, которой нет в этом справочнике, — добавьте её. Внизу страницы есть ссылка «Редактировать страницу»: тридцать секунд вашего времени сэкономят чей-то вечер.