Установка на Windows через WSL

Mojo не работает в Windows напрямую — компилятор существует только для macOS и Linux. Но это не значит, что Windows-разработчику сюда нельзя: WSL2 (подсистема Windows для Linux) даёт настоящее ядро Linux внутри Windows, и Mojo в нём работает так же, как на обычной Ubuntu.

Эта глава проведёт вас весь путь: от проверки, потянет ли ваш компьютер, до момента, когда в VS Code работает автодополнение и первая программа печатает приветствие.

Сколько это займёт

Около 30–40 минут, из которых половина — ожидание скачивания. Понадобится одна перезагрузка Windows и примерно 5 ГБ свободного места на диске C.

Шаг 0. Проверьте, потянет ли ваш компьютер

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

Что	Требование
Windows	Windows 11 (любая версия) или Windows 10 версии 2004+, сборка 19041+
Процессор Intel/AMD	Поддержка x86-64-v3 — Haswell и новее, то есть примерно с 2013 года. Нужны AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, XSAVE
Процессор ARM	Neoverse N1 и новее
Оперативная память	Минимум 8 ГБ
Виртуализация	Включена в BIOS/UEFI (Intel VT-x или AMD-V)
Место на диске	~5 ГБ для WSL + Ubuntu + Mojo

Проверить сборку Windows: нажмите Win + R, введите winver, нажмите Enter. В окне будет строка вида «Сборка ОС 22631.4317» — число до точки должно быть 19041 или больше.

Проверить, включена ли виртуализация: откройте «Диспетчер задач» → вкладка «Производительность» → «ЦП». Справа внизу должна быть строка «Виртуализация: Включено». Если написано «Отключено» — придётся зайти в BIOS, см. разбор ошибок в конце главы.

Шаг 1. Установите WSL2

1. Откройте PowerShell от имени администратора.

   Нажмите Win, наберите «PowerShell», в результатах нажмите правой кнопкой → «Запуск от имени администратора».

2. Установите WSL вместе с Ubuntu:

   wsl --install -d Ubuntu-24.04

   Команда включит нужные компоненты Windows, скачает ядро Linux и установит Ubuntu 24.04 LTS. Новые установки по умолчанию используют WSL версии 2 — именно она нам и нужна.

   Заметка

   Mojo официально тестируется на Ubuntu 22.04 LTS и новее и требует glibc 2.34+. Ubuntu 24.04 подходит с запасом. Не берите старые дистрибутивы вроде Ubuntu 20.04 — там glibc 2.31, и Mojo не запустится.

3. Перезагрузите Windows.

   Это обязательный шаг, а не рекомендация: компоненты виртуализации включаются только после перезагрузки.

4. Завершите настройку Ubuntu.

   После перезагрузки Ubuntu запустится сама (или откройте её из меню «Пуск»). Она попросит придумать имя пользователя и пароль — это отдельная учётная запись внутри Linux, не связанная с вашей учётной записью Windows.

   Пароль вводится «вслепую», без звёздочек — это нормально для Linux. Запомните его: он понадобится для команд с sudo.

5. Проверьте, что всё встало правильно.

   Вернитесь в PowerShell и выполните:

   wsl --list --verbose

   Ожидаемый вывод

     NAME            STATE           VERSION
   * Ubuntu-24.04    Running         2

   Главное здесь — VERSION 2. Если стоит 1, выполните:

   wsl --set-version Ubuntu-24.04 2

Необязательно: ограничьте аппетиты WSL

По умолчанию WSL2 может забрать до половины оперативной памяти и все ядра процессора. Если во время компиляции у вас начинает тормозить Windows, создайте файл C:\Users\<ВашеИмя>\.wslconfig:

%UserProfile%.wslconfig

[wsl2]
memory=8GB        # сколько ОЗУ максимум может занять Linux
processors=4      # сколько ядер отдать
swap=4GB          # файл подкачки внутри WSL

[experimental]
sparseVhd=true    # виртуальный диск возвращает освободившееся место Windows

Изменения применяются только после полной остановки WSL:

wsl --shutdown

Шаг 2. Установите uv

Дальше всё происходит внутри Ubuntu. Откройте её из меню «Пуск» (или наберите wsl в PowerShell).

Mojo ставится как обычный Python-пакет, и мы будем управлять им через uv — быстрый менеджер пакетов и проектов от Astral. Он же и рекомендуется официальной документацией Mojo.

1. Обновите систему и поставьте компилятор C — он нужен Mojo для линковки:

   sudo apt update && sudo apt install -y build-essential curl

2. Установите uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh

3. Перезапустите оболочку, чтобы uv появился в PATH:

   source ~/.bashrc
   uv --version

Почему uv, а не pixi

Официальная документация предлагает оба варианта — uv и pixi. Мы выбрали uv, потому что он уже стоит у многих разработчиков как замена pip и virtualenv: не придётся держать в голове ещё один менеджер окружений. Если вы предпочитаете pixi — все примеры курса работают и с ним, отличается только команда установки.

Шаг 3. Создайте первый проект и поставьте Mojo

1. Создайте папку для проектов внутри домашней директории Linux:

   mkdir -p ~/projects && cd ~/projects

   Не кладите проекты в /mnt/c

   Соблазн велик: /mnt/c/Users/Вы/Documents — это ваши привычные папки Windows, они видны прямо из Linux. Но обращение к ним идёт через медленный протокол трансляции между Windows и Linux, и компиляция будет ощутимо тормозить, а языковой сервер в редакторе — подвисать.

   Держите код в ~/projects (это /home/вашеимя/projects). Из Windows эти файлы тоже доступны — через \\wsl$\Ubuntu-24.04\home\вашеимя.

2. Создайте проект:

   uv init hello-mojo
   cd hello-mojo

3. Добавьте Mojo в зависимости:

   uv add mojo

   uv скачает компилятор и стандартную библиотеку в виртуальное окружение проекта. Первый раз это займёт пару минут.

4. Проверьте установку:

   uv run mojo --version

   Должна появиться строка с версией 1.0.0 (или новее, если вышло обновление ветки 1.x).

Структура проекта получится такой:

• Директорияhello-mojo

  • Директория.venv/ виртуальное окружение с компилятором Mojo

    • …
  • pyproject.toml описание проекта и зависимостей
  • uv.lock точные версии всех пакетов
  • main.py создан uv по умолчанию, можно удалить

Шаг 4. Первая программа

Создайте файл hello.mojo:

~/projects/hello-mojo/hello.mojo

def main():
    print("Привет, Mojo!")

Запустите:

uv run mojo hello.mojo

Результат

Привет, Mojo!

Если вы видите эту строку — Mojo установлен и работает. Дальше настроим редактор, чтобы писать код было приятно.

Почему `def`, а не `fn`

Если вы читали статьи про Mojo 2023–2025 годов, вы наверняка видели там fn main(). В Mojo 1.0 ключевое слово fn объявлено устаревшим — вся документация и весь новый код используют только def. Подробнее об этом и других изменениях — в главе Функции.

Шаг 5. Настройте VS Code

Здесь есть неочевидный момент, из-за которого спотыкаются почти все: VS Code устанавливается в Windows, а работать должен внутри WSL. Между этими двумя мирами он строит мост — расширение Remote — WSL.

1. Установите VS Code в Windows — обычным установщиком с code.visualstudio.com, не внутри Ubuntu.

2. Поставьте расширение WSL (ms-vscode-remote.remote-wsl).

   Найдите его в панели расширений по слову «WSL», издатель — Microsoft.

3. Откройте проект из Linux-терминала:

   cd ~/projects/hello-mojo
   code .

   Первый запуск займёт время: VS Code доустановит свою серверную часть внутрь Ubuntu. В левом нижнем углу окна появится синий индикатор WSL: Ubuntu-24.04 — это признак, что редактор работает на стороне Linux.

   Не открывайте папку через `\\wsl$`

   Если открыть проект в VS Code через «Файл → Открыть папку» и путь \\wsl$\Ubuntu-24.04\home\..., редактор будет работать на стороне Windows и обращаться к файлам по сети. Расширение Mojo не найдёт компилятор, а терминал будет запускать PowerShell вместо bash. Правильный способ ровно один — команда code . из Linux-терминала.

4. Установите расширение Mojo 🔥 (modular-mojotools.vscode-mojo).

   Важно: устанавливать нужно в WSL, а не локально. В панели расширений у кнопки будет написано «Install in WSL: Ubuntu-24.04» — это то, что нужно. Расширение даёт автодополнение, подсказки по документации, переход к определению, форматирование и отладчик на базе LLDB.

5. Проверьте, что расширение нашло Mojo.

   Внизу в строке состояния должен отображаться статус SDK. Если появилось сообщение, что окружение Mojo не найдено — выполните команду Python: Select Interpreter (Ctrl + Shift + P) и выберите интерпретатор из .venv вашего проекта. Расширение определяет SDK в том числе через выбранное Python-окружение.

   Если и это не помогло, укажите путь явно в настройках рабочей области:

   .vscode/settings.json

   {
     "mojo.sdk.path": "/home/вашеимя/projects/hello-mojo/.venv"
   }

   Путь обязательно абсолютный: подстановки вроде ${workspaceFolder} расширение не понимает. Подробный разбор — в главе Настройка VS Code.

Известная шероховатость

У расширения Mojo исторически бывали проблемы с определением SDK именно в удалённых сессиях (WSL и SSH) — оно не всегда подхватывает переменные окружения удалённой оболочки. Если автоопределение капризничает, явное указание mojo.sdk.path в настройках рабочей области решает вопрос надёжнее всего.

Шаг 6. Git и подключение к репозиторию

Git внутри WSL — это отдельный Git, не тот, что стоит в Windows. Настроим его.

1. Представьтесь Git:

   git config --global user.name "Ваше Имя"
   git config --global user.email "you@example.com"

2. Создайте SSH-ключ:

   ssh-keygen -t ed25519 -C "you@example.com"

   На все вопросы можно нажимать Enter — путь по умолчанию подойдёт. Пароль на ключ (passphrase) ставить не обязательно, но желательно.

3. Добавьте ключ в агент:

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519

4. Скопируйте публичный ключ:

   cat ~/.ssh/id_ed25519.pub

   Скопируйте всю выведенную строку и добавьте её на GitHub: Settings → SSH and GPG keys → New SSH key.

5. Проверьте соединение:

   ssh -T git@github.com

   Ожидаемый вывод

   Hi username! You've successfully authenticated, but GitHub does not provide shell access.

   Фраза про отсутствие shell-доступа — это не ошибка, а нормальный ответ.

Теперь можно клонировать репозитории прямо в WSL и открывать их через code .. Тот же подход работает и для удалённых машин — только вместо расширения WSL используется Remote - SSH (ms-vscode-remote.remote-ssh): вы подключаетесь к серверу, а VS Code работает так, будто код лежит локально.

Типичные ошибки и что с ними делать

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

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

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

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

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

WslRegisterDistribution failed with error: 0x8007019e

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

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

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

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

mojo: command not found

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

Вы вызываете mojo напрямую, а он установлен внутрь окружения проекта, которое сейчас не активировано.

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

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

Другие частые ситуации

Симптом	Причина и решение
Конфликт с VirtualBox или VMware	Обновите их: VMware — 15.5.5+, VirtualBox — 6.0+. Старые версии не уживаются с гипервизором Windows
Компиляция очень медленная	Проект лежит в /mnt/c/.... Перенесите в ~/projects
В VS Code нет автодополнения Mojo	Расширение Mojo установлено локально, а не в WSL. В панели расширений нажмите «Install in WSL»
Кончилось место на диске C	Виртуальный диск WSL растёт динамически и по умолчанию живёт на C. Включите sparseVhd=true в .wslconfig или перенесите дистрибутив на другой диск через wsl --export / wsl --import
wsl --install пишет, что команда не найдена	Слишком старая сборка Windows 10. Обновитесь до сборки 19041+

🎯 Проверь себя

Почему проект нельзя держать в папке Windows, доступной как /mnt/c?

Обращение к файлам Windows изнутри Linux идёт через прослойку трансляции и работает заметно медленнее, чем к родной файловой системе WSL. На компиляции и работе языкового сервера это чувствуется сразу. Держите код в ~/projects.

Чем `code .` из Linux-терминала отличается от открытия папки через \\wsl$?

code . запускает VS Code в режиме WSL: серверная часть редактора работает внутри Linux, расширения видят компилятор, терминал — это bash. При открытии через \\wsl$ редактор остаётся Windows-приложением и обращается к файлам по сети — Mojo не находится, автодополнение не работает.

Что делает команда `uv add mojo`, и почему после неё `mojo` не запускается напрямую?

Она добавляет Mojo в зависимости проекта и ставит компилятор в виртуальное окружение .venv этого проекта, а не в систему целиком. Поэтому запускать нужно через uv run mojo ... либо предварительно активировать окружение.

Что дальше

Окружение готово. Дальше — первая настоящая программа и разбор того, чем Mojo отличается от Python на уровне синтаксиса.