Настройка VS Code

Официальное расширение Modular превращает VS Code в полноценную среду для Mojo: автодополнение, подсказки по документации, переход к определению, форматирование, запуск файла и отладчик на базе LLDB.

Что умеет расширение

• подсветка синтаксиса .mojo;
• автодополнение кода;
• диагностика ошибок с быстрыми исправлениями;
• переход к символу и документация во всплывающей подсказке;
• форматирование кода;
• запуск и отладка файла прямо из редактора;
• полноценная работа языкового сервера внутри блоков кода в докстрингах — редкая возможность, которой нет почти нигде.

Установка

1. Поставьте расширение Mojo 🔥 (modular-mojotools.vscode-mojo) — издатель Modular.

   Для Windows: устанавливать нужно в WSL

   Если вы работаете через WSL, у кнопки установки будет написано Install in WSL: Ubuntu-24.04. Нужен именно этот вариант: расширение должно жить рядом с компилятором, то есть на стороне Linux. Установленное «локально», в Windows, оно не найдёт SDK и не даст ни автодополнения, ни отладчика.

2. Поставьте расширение Python (ms-python.python).

   Формально оно не обязательно, но именно через него расширение Mojo находит окружение с установленным SDK. Без него в строке состояния появится предложение его установить.

3. Откройте папку проекта — ту, где лежат pyproject.toml и .venv.

   На Windows открывать нужно командой code . из терминала Ubuntu, а не через «Файл → Открыть папку». Подробнее — в главе Установка на Windows через WSL.

4. Откройте любой файл .mojo.

   В строке состояния внизу слева появится статус SDK: либо сведения о найденном окружении, либо кликабельное сообщение, что SDK не найден.

Как расширение находит SDK

Это главный источник недоразумений, поэтому разберём порядок поиска. Расширение выбирает окружение так, сверху вниз:

1. Настройка mojo.sdk.path. Если она задана — используется только она, без всякого автоопределения.

2. SDK монорепозитория — папка .derived/ в открытой рабочей области. Это вариант для тех, кто собирает Mojo из исходников; обычному читателю он не встретится.

3. Окружение Python, найденное через расширение Python. Именно так находятся установки через uv и pixi.

Если автоопределение промахнулось, порядок действий такой:

1. Выполните команду Python: Select Interpreter (Ctrl + Shift + P) и выберите интерпретатор из .venv вашего проекта.

   Расширение Python иногда по умолчанию цепляется за глобальное окружение, даже когда в проекте есть своё — это самая частая причина «SDK не найден».

2. Если не помогло — укажите путь явно. Создайте в проекте файл .vscode/settings.json:

   .vscode/settings.json

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

   Путь должен быть абсолютным

   Подстановки вроде ${workspaceFolder} здесь не работают: расширение ждёт абсолютный путь к корню окружения. Для установки через uv это папка .venv — в ней лежат bin/mojo и lib/python*/site-packages/modular/. Для установки через pixi — папка вида .pixi/envs/default, содержащая share/max/modular.cfg.

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

3. После правки настроек выполните команду Refresh SDK Detection или Restart the Extension.

Настройку лучше держать в проекте, а не в профиле

mojo.sdk.path можно задать глобально, но правильнее — на уровне рабочей области, то есть в .vscode/settings.json внутри проекта. У разных проектов свои окружения, и глобальный путь рано или поздно начнёт мешать. Файл .vscode/settings.json при этом полезно закоммитить: коллегам не придётся настраивать то же самое руками.

Запуск и отладка

Самый быстрый способ — стрелка вниз рядом с кнопкой ▶️ в правом верхнем углу открытого файла .mojo: там есть Run Mojo File и Debug Mojo File.

Для постоянной конфигурации создайте .vscode/launch.json. Расширение предлагает готовые шаблоны; вот тот, что нужен в 90% случаев:

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "mojo-lldb",
      "request": "launch",
      "name": "Mojo: отладить текущий файл",
      "mojoFile": "${file}",
      "args": [],
      "env": [],
      "cwd": "${workspaceFolder}",
      "runInTerminal": false
    }
  ]
}

Полезные поля конфигурации:

Поле	Что делает
mojoFile	Файл .mojo, который нужно собрать и запустить под отладчиком. Имеет приоритет над program
program	Путь к уже собранному исполняемому файлу — если хотите отлаживать результат mojo build
args	Аргументы командной строки программы
buildArgs	Аргументы сборки, когда используется mojoFile
env	Дополнительные переменные окружения, массив строк вида ИМЯ=значение
cwd	Рабочая директория программы
stopOnEntry	Остановиться сразу на первой инструкции
runInTerminal	Запускать во встроенном терминале — нужно, если программа читает ввод пользователя

Отладчик — это LLDB, поставляемый вместе с Mojo. Работают точки останова, пошаговое выполнение, просмотр значений переменных, стек вызовов и консоль отладчика. Есть и отдельный тип конфигурации mojo-cuda-gdb — для отладки кода, исполняющегося на GPU NVIDIA.

Чтобы подключиться к уже запущенному процессу, используйте команду Attach to Process или конфигурацию с "request": "attach" и указанием pid либо program.

Если программа ждёт ввод с клавиатуры

По умолчанию отладчик запускает программу без терминала, и input() повиснет без объяснений. Поставьте "runInTerminal": true.

Полезные команды

Все они вызываются через Ctrl + Shift + P:

Команда	Зачем
Mojo: Run Mojo File	Собрать и запустить текущий файл
Mojo: Debug Mojo File	То же, но под отладчиком
Mojo: Debug Mojo File in Terminal	Отладка с полноценным терминалом
Mojo: Configure Build and Run Args	Задать аргументы сборки и запуска
Mojo: Refresh SDK Detection	Перечитать окружение после смены интерпретатора
Mojo: Restart the Extension	Первое, что стоит попробовать, когда «всё сломалось»
Mojo: Restart the Mojo LSP Server	Перезапустить только языковой сервер
Mojo: Attach to Process	Подключиться к запущенному процессу

Настройки

Настройка	По умолчанию	Что делает
mojo.sdk.path	пусто	Абсолютный путь к окружению с SDK. Отменяет автоопределение
mojo.preferWorkspaceEnv	true	Предпочитать окружение, найденное в рабочей области (.venv, .pixi/envs/*), а не глобальное
mojo.lsp.includeDirs	не задано	Дополнительные каталоги для поиска импортируемых модулей
mojo.lsp.suppress.diagnostics.in.docstring	false	Не показывать ошибки в примерах кода внутри докстрингов
mojo.formatting.args	не задано	Аргументы форматировщика, по одному элементу массива на аргумент
mojo.run.focusOnTerminalAfterLaunch	false	Переводить фокус в терминал после запуска файла
mojo.onSettingsChanged	prompt	Что делать, когда изменение настройки требует перезапуска расширения

Форматирование при сохранении

Расширение регистрируется как форматировщик для Mojo, поэтому включается это стандартными настройками VS Code:

.vscode/settings.json

{
  "[mojo]": {
    "editor.defaultFormatter": "modular-mojotools.vscode-mojo",
    "editor.formatOnSave": true
  }
}

Когда что-то не работает

Mojo SDK not found

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

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

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

По порядку: Python: Select Interpreter → выбрать .venv проекта → Mojo: Refresh SDK Detection. Если не помогло — прописать mojo.sdk.path абсолютным путём и перезапустить расширение.

Автодополнение молчит, ошибки не подсвечиваются, хотя файл открыт

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

Языковой сервер не запустился или упал. Такое случается после обновления SDK или переключения окружения.

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

Команда Mojo: Restart the Mojo LSP Server. Если не помогает — Mojo: Restart the Extension. Логи смотрите в панели «Вывод», выбрав в списке канал Mojo.

Импорт своего модуля подчёркнут красным, но программа компилируется

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

Языковой сервер не знает, где искать модуль: его каталог не входит в список путей поиска.

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

Добавьте каталог в mojo.lsp.includeDirs в настройках рабочей области.

Известная шероховатость в удалённых сессиях

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

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

Почему расширению Mojo нужно расширение Python?

Через него расширение Mojo узнаёт, какое виртуальное окружение выбрано в проекте, — а компилятор Mojo лежит именно внутри окружения, созданного uv или pixi. Без этого источника остаётся только ручная настройка mojo.sdk.path.

Куда указывать mojo.sdk.path при установке через uv?

На папку .venv проекта, абсолютным путём. Именно она содержит bin/mojo и lib/python*/site-packages/modular/. Подстановки вроде ${workspaceFolder} не поддерживаются.

Программа под отладчиком ждёт input(), но ничего ввести нельзя. Что поменять?

Добавить в конфигурацию отладки "runInTerminal": true — тогда программа запустится во встроенном терминале и сможет читать ввод.

Что дальше

Если работаете не на своей машине — настроим удалённую разработку: SSH, контейнеры и Codespaces. Если всё готово — переходите к первой программе.