Что делать, если JupyterLab 4.6 не находит ядро Python?

В официальном журнале изменений стабильной документации JupyterLab для ветки 4.6 указана версия 4.6.5 (журнал изменений JupyterLab). Если JupyterLab 4.6 не находит ядро Python, сначала выясните, в какой среде запущена служба, затем установите ipykernel в нужную среду и зарегистрируйте её как ядро. Не переустанавливайте JupyterLab, пока не проверили эту связь; после регистрации проверьте интерпретатор и зависимости внутри Notebook.

Эта инструкция для студентов и сотрудников лабораторий, у которых список ядер пуст или не содержит среды проекта.
Она также пригодится после смены виртуальной среды, Conda-окружения или версии Python.
Технические специалисты, поддерживающие Mac для лаборатории, найдут здесь порядок диагностики и критерии приёмки.

Что именно означает отсутствие ядра в JupyterLab 4.6

JupyterLab, сервер Jupyter и ядро Notebook связаны, но это не один и тот же компонент. Интерфейс может открываться и показывать файлы, даже если нужная среда Python не зарегистрирована как ядро. Документация JupyterLab описывает выбор ядра для документа отдельно от самого интерфейса (работа с документами и ядрами).

Полезно различать несколько состояний:

• Ядер нет вообще. Служба не находит подходящий kernelspec или не может запустить ядро.
• Есть системное Python-ядро, но нет среды проекта. Python установлен, однако его среда не зарегистрирована для Jupyter.
• Ядро видно, но Notebook использует не тот Python. Выбранное ядро запускается, но указывает на другой интерпретатор.
• Ядро запускается, но научный расчёт не проходит. Интерпретатор работает, однако в нём нет требуемых библиотек, файлов или настроек проекта.

До исправления запишите способ запуска JupyterLab, путь к каталогу проекта, имя нужной среды и точный результат в списке ядер. Если сервер запущен из терминала, проверьте именно тот терминал и пользователя, а не другое окно, в котором доступен Python. При запуске через службу или графический ярлык контекст может отличаться от интерактивной оболочки.

Важно. Команда python в терминале показывает, что доступен некоторый Python. Она не доказывает, что JupyterLab обнаружил его или что Notebook использует именно его.

Диагностика по признакам: нет ни одного ядра или пропала одна среда

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

Откройте терминал в том же контексте, откуда обычно запускается JupyterLab, и выполните:

jupyter lab --version
jupyter kernelspec list

Первая команда показывает версию доступного запускаемого JupyterLab. Вторая выводит известные Jupyter спецификации ядер и их расположение. Управление ядрами и kernelspec описано в документации Jupyter Client (список и устройство ядер). Если команда jupyter не находится, это ещё не говорит, что Python отсутствует: возможно, оболочка использует другой путь или JupyterLab стартует через отдельную службу.

Затем сопоставьте результат с тем, как запускается сервер. Конфигурация Jupyter Server определяет параметры службы и её рабочую среду (документация по конфигурации Jupyter Server). Если команда показывает ядро, но меню его не обновило, перезагрузите страницу или перезапустите службу после проверки. Если не показывает, продолжайте диагностику в целевой среде.

Сравнение вариантов диагностики и исправления

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

Целевая среда не появляется: проверьте ipykernel и регистрацию

Наличие установленного ipykernel недостаточно, если он относится не к тому Python. Например, команда pip install ipykernel, выполненная без проверки, может установить пакет в интерпретатор, отличный от проектного. Поэтому сначала найдите исполняемый файл среды. Для виртуальной среды Python укажите явный путь к её Python; устройство таких сред описано в официальной документации Python (модуль venv).

Дальше используйте этот интерпретатор и для установки, и для регистрации. В примере замените путь на фактический путь к среде проекта:

/path/to/project-env/bin/python -m pip install ipykernel
/path/to/project-env/bin/python -m ipykernel install --user --name project-env --display-name "Python (project-env)"

Официальная инструкция IPython показывает, как установить ядро из отдельного Python-окружения и задать ему имя (установка IPython kernelspec). Параметр --name задаёт внутреннее имя спецификации, а --display-name — подпись в списке JupyterLab. Подпись можно сделать понятной для исследовательской группы, но она не доказывает, какой файл Python будет запущен. Доказательство — путь в kernelspec и проверка из самого Notebook.

После регистрации снова выполните jupyter kernelspec list в среде службы. Если новый kernelspec не отображается, проверьте, под каким пользователем запускается JupyterLab и где этот пользователь ищет спецификации. Не удаляйте другие ядра наугад: сначала сохраните их имена и пути, особенно если ими пользуются коллеги.

При смене окружения безопаснее зарегистрировать новое ядро с отдельным именем, чем заменять старое. Тогда старые Notebook и рабочие процессы останутся доступны, а новую среду можно будет проверить отдельно. Удалять старую регистрацию стоит только после подтверждения, что она больше не нужна и ни один проект на неё не ссылается.

Частые вопросы

JupyterLab открывается, но в списке нет Python

Сначала выполните jupyter kernelspec list из того же контекста, откуда запущен сервер. Если список пуст, проверьте установку ядра и конфигурацию службы. Если видны другие ядра, но не нужная среда, зарегистрируйте Python проекта через ipykernel. Перезапускать или переустанавливать JupyterLab имеет смысл только после проверки этой связи.

ipykernel установлен в виртуальной среде, но JupyterLab её не показывает

Проверьте, к какому Python относится pip: используйте целевой интерпретатор в форме python -m pip, а не непроверенную команду pip. Затем из того же Python зарегистрируйте ядро отдельным kernelspec. Важно проверить результат со стороны запущенной службы: терминальная команда в другом окружении может видеть иной набор ядер.

Как проверить, какой Python выполняет Notebook

В ячейке выполните import sys и выведите sys.executable. Сравните путь с ожидаемым Python среды проекта. Название ядра в меню может быть произвольным, поэтому ориентироваться только на него нельзя. Затем проверьте версии ключевых библиотек и выполните короткий импорт используемых в проекте модулей.

Как подключить старый Notebook к новой среде

Установите ipykernel в новую среду и зарегистрируйте её, не меняя старый файл вручную. Откройте Notebook, выберите новое ядро и выполните проверку sys.executable, затем проверьте импорты проекта. Если всё совпадает, сохраните Notebook. Для воспроизводимости отдельно запишите способ создания среды и список критичных зависимостей.

Ядро видно, но код использует не тот Python

После выбора ядра выполните в Notebook короткую диагностическую ячейку:

import os
import sys

print(sys.executable)
print(sys.version)
print(os.getcwd())

sys.executable показывает путь к интерпретатору текущего процесса. sys.version помогает подтвердить версию Python, а os.getcwd() — рабочий каталог, из которого код ищет относительные файлы. Эти проверки отвечают на разные вопросы: выбран ли нужный Python и откуда запускаются операции с файлами.

Затем проверьте не только наличие пакетов, но и то, что проверка проходит именно в выбранном ядре:

from importlib.metadata import version

print(version("ИМЯ_ПАКЕТА"))

Подставьте имя ключевой зависимости проекта. Если библиотека не находится, не устанавливайте её автоматически в «глобальный» Python. Сначала сверьте sys.executable, затем установите пакет способом, принятым для этого проекта, в подтверждённую среду. Это уменьшает риск изменить окружение другого Notebook или нарушить зафиксированные версии.

Рабочий каталог тоже важен для научного анализа. Notebook может открыться из другой папки и не найти данные или локальные модули, хотя ядро корректно. Проверьте, откуда запускается сервер и какой каталог выбран для проекта. Не переносите чувствительные исследовательские данные в стороннюю среду ради проверки; для диагностики обычно достаточно кода без реальных данных и безопасных тестовых файлов.

Регистрация выполнена, но ядро не стартует или отключается

Если ядро появляется в меню, но сразу завершается, сначала проверьте путь, указанный в kernelspec. Среду могли переместить, переименовать или удалить; в этом случае регистрация останется в списке, но запуск будет указывать на недоступный Python. Посмотрите путь к спецификации из вывода jupyter kernelspec list, затем откройте соответствующий файл и проверьте его команду запуска. Не редактируйте его до сохранения исходной копии.

Второй источник путаницы — разные машины или контексты запуска. Терминал на локальном Mac, удалённый сервер и ядро могут не разделять файловую систему. Проверяйте путь на том хосте, где реально выполняется Jupyter Server и запускается Python-процесс. Если Notebook открыт через удалённую службу, наличие среды в локальном терминале не подтверждает её доступность на сервере.

Для сужения причины запустите минимальный фрагмент без чтения данных и импорта тяжёлых библиотек. Если пустая ячейка завершается, зафиксируйте сообщение сервера и проверьте kernelspec и доступность указанного Python. Если минимальный код работает, а сбой появляется при импорте или загрузке проекта, проверяйте соответствующую зависимость, рабочий каталог и доступ к файлам отдельно. Не следует называть такой случай общей неисправностью JupyterLab 4.6 без подтверждённых данных.

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

Порядок проверки перед возвращением к исследовательской работе

Используйте этот контрольный список после исправления:

• [ ] Запишите версию JupyterLab, способ запуска службы и путь к проекту.
• [ ] Убедитесь, что целевая среда видна в выводе jupyter kernelspec list.
• [ ] В интерфейсе выберите ядро проекта, а не похожее по названию системное ядро.
• [ ] В Notebook проверьте sys.executable, версию Python и рабочий каталог.
• [ ] Импортируйте критичные зависимости и проверьте их версии в выбранном ядре.
• [ ] Запустите короткий безопасный этап анализа на тестовых или обезличенных данных.
• [ ] Сохраните информацию о среде и выбранном ядре рядом с проектной документацией.

Сохраните также команды запуска и регистрации, но не секреты доступа, токены или персональные данные. Если работу должна повторять лаборатория, зафиксируйте точный путь к среде и процедуру её создания. Название ядра само по себе для воспроизведения недостаточно: другой пользователь может зарегистрировать такое же отображаемое имя для другого Python.

JupyterLab 4.6.5 указан в официальном журнале изменений для ветки 4.6; перед публикацией инструкции по конкретной установке сверяйте текущую документацию и доступные команды. Сам принцип диагностики остаётся раздельным: служба обнаруживает kernelspec, kernelspec запускает Python, а Notebook выполняет код в выбранном ядре. Подтверждать нужно каждую из этих частей.

Если проекту действительно требуется проверка именно на macOS, а у лаборатории нет доступного Mac, удалённый Mac может дополнить Linux- и Windows-среды. Он не заменяет диагностику kernelspec и не гарантирует совместимость конкретного проекта. До передачи кода и данных проверьте требования к конфиденциальности, нужный способ доступа и то, допускает ли проект удалённое выполнение. Сначала можно изучить руководства по удалённой работе с Mac, примеры сценариев и сравнение вариантов доступа к Mac. При оценке аренды Mac учитывайте условия предоставления доступа и соответствие среды требованиям проекта; выбор следует делать после проверки конфиденциальности и способа подключения.

Часто задаваемые вопросы