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

#Что произошло и когда проявляется ошибка

При запуске Python из другого каталога импорт локального модуля может не найти файл: важны расположение стартового скрипта, способ запуска (-m) и реальный sys.path, а не только текущая папка оболочки.

#Причины и диагностические признаки

#Подробная пошаговая диагностика и исправление

1. 1. Уточните расположение файлов и командуОткройте папку проекта в Проводнике или файловом менеджере редактора. Запишите путь к запускаемому файлу и модулю, который не импортируется. В терминале перейдите в корень проекта; проверьте, что локальный модуль находится внутри проекта, а имя в import совпадает с именем файла без .py.
2. Linux/macOS: выполняйте в обычном терминале; Windows замените pwd на cd

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Linux/macOS: выполняйте в обычном терминале; Windows замените pwd на cd. Администратор не нужен.

   pwd

   python -c "import os,sys; print(os.getcwd()); print(sys.executable); print(*sys.path,sep=chr(10))"

1. 2. Определите, какой способ запуска ломаетсяВ каталоге проекта выполните стартовый модуль так, как обычно. Если ошибка возникает при запуске python tools/run.py, сравните с python -m tools.run из корня проекта: второе выполняет модуль как часть пакета. Если команда -m не работает, проверьте имя пакета и вложенных каталогов.

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Замените tools.run реальным полным именем модуля; пример применим к проекту с tools/run.py.

   python -m tools.run

1. 3. Проверьте фактический поиск модуляСоздайте временный diagnose_import.py рядом со стартовым файлом, вставьте пример и запустите тем же способом. find_spec покажет путь найденного модуля или None; не импортируйте его содержимое ради проверки. Если обнаружится json.py проекта вместо стандартного json, переименуйте файл и соответствующие импорты.
2. Пример кода по теме

   PythonКопировать всёВыделить

   Образец кода для файла .py в тестовой копии проекта; перед внедрением замените имена файлов на реальные.

   import importlib.util, os, sys
   print("cwd:", os.getcwd())
   print("python:", sys.executable)
   print("sys.path:", sys.path)
   print("utils:", importlib.util.find_spec("utils"))

1. 4. Исправьте импорты внутри пакетаЕсли файлы app/main.py и app/helpers.py принадлежат одному пакету, используйте в main.py from . import helpers, а запускайте пакет из родительского каталога как python -m app.main. Не вставляйте в продакшен бездумный sys.path.append и не меняйте глобальную PYTHONPATH ради обхода ошибки.
2. Пример кода по теме

   PythonКопировать всёВыделить

   Образец кода для файла .py в тестовой копии проекта; перед внедрением замените имена файлов на реальные.

   from . import helpers
   # запуск из каталога, содержащего папку app:
   # python -m app.main

1. 5. Повторите запуск из обоих местЗакройте интерактивный Python, чтобы исключить старые значения sys.modules. Из корня проекта и из каталога, из которого запускается задача, воспроизведите штатную команду. Убедитесь, что исчезло ModuleNotFoundError, а импорт указывает на нужный файл проекта, не на одноимённую библиотеку.

#Как проверить, что проблема устранена

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

#Если исправление не помогло

Если нужен запуск из произвольной папки, используйте абсолютный путь к проекту и точку входа с -m либо корректно устанавливаемый пакет. Если модуль отсутствует в виртуальном окружении, переходите к проверке окружения, а не меняйте импорты.