Настройка путей импорта в Python: от PYTHONPATH до .pth файлов

Расширенные примеры конфигурации путей Python

1. Динамическое добавление путей с проверкой существования

При добавлении путей в sys.path внутри скрипта стоит проверять, что каталог действительно существует. Это предотвращает неожиданные ошибки импорта.

import sys
import os
from pathlib import Path

def add_path(path):
    p = Path(path).resolve()
    if p.is_dir() and str(p) not in sys.path:
        sys.path.insert(0, str(p))
        print(f'Добавлен путь: {p}')
    else:
        print(f'Путь {p} не существует или уже в sys.path')

add_path('/tmp/non_existent')  # выведет предупреждение
add_path('/usr/lib/python3')   # добавит, если каталог существует

Путь /tmp/non_existent не существует или уже в sys.path
Добавлен путь: /usr/lib/python3

2. Использование .pth файла в пользовательском каталоге site.USER_SITE

Каждый пользователь может иметь собственный каталог site-packages (вывод python -m site --user-site). Размещение .pth файла там добавит пути только для данного пользователя, не затрагивая других.

# Определяем каталог user-site
python -m site --user-site
# Пример вывода: /home/alice/.local/lib/python3.11/site-packages

# Создаём файл custom.pth в этом каталоге
mkdir -p /home/alice/.local/lib/python3.11/site-packages
echo '/home/alice/dev/libs' > /home/alice/.local/lib/python3.11/site-packages/custom.pth

После этого любой скрипт, запущенный от пользователя alice, сможет импортировать модули из /home/alice/dev/libs. Для других пользователей этот путь не будет виден.

3. Отладка sys.path с помощью вывода содержимого

Иногда полезно вывести полный sys.path для понимания, какие каталоги приоритетны.

import sys
print('Текущий sys.path:')
for i, path in enumerate(sys.path):
    print(f'{i}: {path}')

Текущий sys.path:
0: /home/user/project
1: /usr/lib/python311.zip
2: /usr/lib/python3.11
3: /usr/lib/python3.11/lib-dynload
4: /usr/lib/python3.11/site-packages

Если после sys.path.insert(0, '/my/path') добавить аналогичный вывод, можно убедиться, что путь появился на позиции 0.

4. Использование переменной PYTHONPATH в комбинации с .pth

Можно одновременно использовать и PYTHONPATH, и .pth файлы. Python обрабатывает их в следующем порядке:

1. Пути из PYTHONPATH (в начале sys.path)
2. Пути из .pth файлов (добавляются после, но могут быть переопределены, если .pth использует import)
3. Стандартные каталоги (lib-dynload, site-packages).

# В терминале:
export PYTHONPATH="/tmp/extra1"
python -c "import sys; print(sys.path[:3])"
# Вывод: ['/tmp/extra1', '/usr/lib/python311.zip', '/usr/lib/python3.11']

Теперь добавьте .pth файл с путём /tmp/extra2. Запустите Python снова - /tmp/extra2 появится после site-packages (если .pth лежит в site-packages) или сразу после /tmp/extra1 (если .pth расположен в другом обрабатываемом каталоге, например, в /usr/lib/python3.11).

5. Обработка ошибки ModuleNotFoundError с помощью отладки путей

Самая частая проблема - импорт модуля, который не находится в sys.path. Сценарий отладки:

# Допустим, модуль my_module не находится
import sys
print('Путь к ожидаемому модулю:', '/opt/mymodule')
print('sys.path содержит:', '/opt/mymodule' in sys.path)
# Если False – нужно добавить путь
if '/opt/mymodule' not in sys.path:
    sys.path.insert(0, '/opt/mymodule')
try:
    import my_module
except ModuleNotFoundError as e:
    print(f'Ошибка: {e}')
    print('Проверьте, что каталог содержит файл __init__.py или сам модуль.')

Такой подход помогает локализовать проблему: либо путь отсутствует в sys.path, либо модуль физически не существует в указанном каталоге.

6. Работа с относительными путями в .pth файлах

В .pth файле можно указывать пути относительно каталога, в котором находится сам .pth файл. Это удобно для переносимых конфигураций.

# Файл /opt/myapp/paths.pth (помещён в site-packages)
../lib
../plugins

Пути будут вычислены относительно /opt/myapp (каталог, содержащий paths.pth). В итоге в sys.path попадут /opt/myapp/lib и /opt/myapp/plugins.