Ошибка "mvn" не является внутренней или внешней командой, исполняемой программой или пакетным файлом появляется в командной строке Windows, когда система не может найти исполняемый файл Maven по указанному пути. Чаще всего причина одна из трёх: Maven вообще не установлен, переменная окружения PATH не содержит путь к папке bin дистрибутива, либо терминал был открыт до изменения переменных и не подхватил обновления. Хорошая новость — проблема решается за несколько минут без переустановки системы.
В этой инструкции разберём диагностику по шагам: как проверить, установлен ли Maven, как правильно прописать переменные окружения JAVA_HOME и MAVEN_HOME, что делать, если ошибка возникает в IntelliJ IDEA или VS Code, хотя в обычной консоли всё работает. Материал актуален для Windows 10 и Windows 11.
Шаг 1. Проверяем, установлен ли Maven
Прежде чем трогать переменные окружения, убедитесь, что дистрибутив Maven вообще есть на диске. Maven не имеет инсталлятора — это архив, который нужно вручную скачать с официального сайта проекта Apache Maven и распаковать.
Откройте Проводник и проверьте типичные места размещения: C:\Program Files\Apache\maven, C:\apache-maven-x.x.x или папку, куда вы распаковывали архив. Внутри должна быть структура каталогов bin, boot, conf, lib. Критически важен файл mvn.cmd в подпапке bin — именно его Windows пытается запустить при вводе команды mvn.
Если папки нет, скачайте архив Binary zip archive с официального сайта Apache Maven и распакуйте его в каталог без пробелов и кириллицы в пути, например C:\apache-maven-3.9.9. Русские буквы и пробелы в пути — частый источник неочевидных сбоев при запуске скриптов сборки.
Шаг 2. Диагностируем проблему через командную строку
Быстрая проверка поможет понять, видит ли система Maven в принципе. Откройте командную строку (Win + R → cmd) и выполните:
where mvnЕсли команда ничего не вернула или выдала сообщение, что файлы не найдены, — путь к Maven отсутствует в PATH. Далее проверьте Java, поскольку Maven без неё не работает:
java -version
echo %JAVA_HOME%
Первая команда должна вывести версию установленной JDK, вторая — путь к каталогу Java. Пустой вывод echo %JAVA_HOME% означает, что переменная не задана, и даже корректно настроенный Maven завершится ошибкой при запуске.
- 🔍
where mvn— показывает, найден ли исполняемый файл в PATH - ☕
java -version— проверяет наличие и версию JDK - 📂
echo %JAVA_HOME%— проверяет переменную окружения Java - 🧪
echo %PATH%— выводит полный список путей для визуальной проверки
Шаг 3. Настраиваем переменные окружения
Это ключевой этап. Откройте Параметры → Система → О системе → Дополнительные параметры системы → Переменные среды (или введите sysdm.cpl через Win + R и перейдите на вкладку «Дополнительно»). Работайте в разделе «Системные переменные», чтобы настройка действовала для всех пользователей.
Создайте или отредактируйте три переменные. Значения приведены как пример — подставьте свои реальные пути:
- ⚙️
JAVA_HOME→ путь к JDK, напримерC:\Program Files\Java\jdk-17(без\binв конце) - 📦
MAVEN_HOME→ путь к Maven, напримерC:\apache-maven-3.9.9 - 🛤️ В переменную
Pathдобавьте запись%MAVEN_HOME%\bin(и при необходимости%JAVA_HOME%\bin)
⚠️ Внимание: вJAVA_HOMEиMAVEN_HOMEуказывается корневая папка без\binна конце, а вот вPathдобавляется именно подпапкаbin. Перепутанные пути — самая частая причина, почему ошибка не уходит даже после «правильной» настройки.
☑️ Настройка Maven в Windows
Шаг 4. Перезапускаем терминал и проверяем результат
Windows применяет новые переменные окружения только к процессам, запущенным после их изменения. Уже открытое окно командной строки, PowerShell или терминал в IDE продолжат работать со старым окружением и будут выдавать ту же ошибку, даже если всё настроено верно.
Закройте все окна терминалов и IDE, откройте командную строку заново и выполните:
mvn -versionКорректный ответ содержит версию Maven, путь к Maven home, версию Java и значение JAVA_HOME. Если вместо этого снова появляется ошибка — вернитесь к шагу 2 и проверьте вывод echo %PATH%: найдите там свою запись с Maven глазами, опечатки вроде лишнего слэша или точки с запятой встречаются часто.
Ошибка в IDE: IntelliJ IDEA, Eclipse, VS Code
Отдельный сценарий — команда mvn работает в системной консоли, но не находится во встроенном терминале среды разработки. Причина та же: IDE была запущена до изменения переменных окружения. Полностью закройте среду (проверьте, что процесс завершён в диспетчере задач) и запустите заново. В упорных случаях помогает перезагрузка компьютера.
Учтите, что IntelliJ IDEA поставляется со встроенным (bundled) Maven, который используется для сборки проектов из интерфейса и не зависит от системного PATH. Поэтому сборка через кнопку в IDE может работать, а команда mvn в её терминале — нет. Это нормальное поведение, а не поломка. При желании в настройках IDE можно указать путь к внешнему Maven вместо встроенного.
Как временно запустить mvn без настройки PATH
Можно вызвать Maven по полному пути, например: "C:\apache-maven-3.9.9\bin\mvn.cmd" -version. Либо в текущей сессии cmd выполнить set PATH=%PATH%;C:\apache-maven-3.9.9\bin — настройка будет действовать только до закрытия окна. Это удобно для разовой проверки, но для постоянной работы правильнее настроить переменные окружения.
Типичные ошибки при настройке
Даже опытные разработчики периодически наступают на одни и те же грабли. Сводная таблица поможет быстро сопоставить симптом с причиной:
| Симптом | Вероятная причина | Решение |
|---|---|---|
| mvn не находится после настройки | Терминал не перезапущен | Закрыть и открыть cmd/IDE заново |
| mvn запускается, но ругается на Java | Не задан JAVA_HOME | Создать переменную с путём к JDK |
| Ошибка сразу после «исправления» PATH | В Path путь без \bin или с опечаткой | Проверить запись %MAVEN_HOME%\bin |
| Работает в cmd, не работает в IDE | IDE запущена до изменения переменных | Полностью перезапустить IDE |
| Странные ошибки скриптов при сборке | Пробелы или кириллица в пути к Maven | Переместить дистрибутив в простой путь |
⚠️ Внимание: не редактируйте переменную Path «вслепую», удаляя существующие записи. Случайное удаление системных путей может нарушить работу других программ. Перед изменением скопируйте текущее значение в текстовый файл.
Часто задаваемые вопросы
Нужно ли перезагружать компьютер после настройки PATH?
Обычно достаточно закрыть и заново открыть командную строку или IDE — новые процессы подхватывают обновлённые переменные. Перезагрузка нужна только в редких случаях, когда какая-то программа продолжает видеть старое окружение даже после перезапуска.
Чем отличаются MAVEN_HOME и M2_HOME?
Обе переменные указывают на каталог установки Maven. M2_HOME — устаревший вариант из ранних версий Maven 2/3, современные версии используют MAVEN_HOME. Достаточно задать MAVEN_HOME, но некоторые старые скрипты и инструменты могут требовать M2_HOME — в этом случае задайте обе с одинаковым значением.
Можно ли установить Maven через пакетный менеджер?
Да. В Windows Maven доступен через менеджеры пакетов, например командой winget install Apache.Maven или через Chocolatey и Scoop. Такие установщики обычно прописывают PATH автоматически, но перезапуск терминала всё равно потребуется.
Почему mvn -version показывает не ту версию Java?
Maven берёт Java из переменной JAVA_HOME, а не из PATH. Если в системе несколько JDK, проверьте, куда указывает JAVA_HOME, и при необходимости измените её на нужную версию. После правки снова перезапустите терминал.
Как проверить настройку без прав администратора?
Переменные можно задать на уровне пользователя: в окне «Переменные среды» используйте верхний раздел «Переменные среды пользователя». Создайте там JAVA_HOME, MAVEN_HOME и дополните пользовательский Path записью %MAVEN_HOME%\bin — права администратора для этого не нужны.