Debian/Ubuntu: как исправить apt_pkg ImportError и восстановить python3-apt

Ошибка ImportError: No module named apt_pkg или ModuleNotFoundError: No module named 'apt_pkg' в Debian и Ubuntu почти всегда означает одно: системный Python и пакет python3-apt перестали совпадать. Обычно это случается после ручного обновления Python, подмены /usr/bin/python3, установки альтернативной версии из исходников или неудачного системного апдейта.

Проблема неприятна не только сама по себе. Из-за неё начинают падать утилиты и служебные скрипты, которые используют Python-обвязку APT: add-apt-repository, обновляющие хуки, некоторые post-install сценарии и связанные системные инструменты. Иногда создаётся впечатление, что «сломался apt», хотя реально не импортируется модуль apt_pkg.

Хорошая новость в том, что в большинстве случаев это чинится без переустановки сервера. Главное — не пытаться лечить систему случайными командами из форумов. Если сначала понять, какой Python ожидает дистрибутив и под какую версию собран python3-apt, восстановление обычно занимает немного времени.

Ключевой принцип простой: в Debian и Ubuntu системный Python — часть инфраструктуры пакетного менеджера. Подменять его вручную на рабочем сервере почти всегда плохая идея.

Как выглядит проблема

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

Traceback (most recent call last):
  File "/usr/bin/add-apt-repository", line 3, in <module>
    import apt_pkg
ModuleNotFoundError: No module named 'apt_pkg'

Или в другом системном скрипте:

Traceback (most recent call last):
  File "/usr/lib/cnf-update-db", line 8, in <module>
    import apt_pkg
ImportError: No module named apt_pkg

Иногда ошибка возникает не прямо в apt update, а в соседних Python-скриптах, которые запускаются рядом с APT. Из-за этого диагностика затягивается: кажется, что пакетный менеджер повреждён целиком, хотя проблема локализована в несовместимости системного Python и python3-apt.

Почему возникает apt_pkg ImportError

Модуль apt_pkg — это не обычный Python-файл, а бинарное расширение из пакета python3-apt, собранное под конкретную системную версию Python. Если интерпретатор меняется, а модуль остаётся старым, импорт ломается из-за несовпадения ABI или пути загрузки.

Чаще всего проблема появляется по одной из причин:

• вручную заменили /usr/bin/python3 на другую версию;
• установили Python из исходников в /usr/local и он начал конфликтовать с системным;
• повредился или был удалён пакет python3-apt;
• в систему подмешались пакеты из другого релиза Debian или Ubuntu;
• обновление завершилось частично;
• кто-то скопировал apt_pkg*.so с другой машины или другого релиза.

Самый типичный сценарий — попытка «обновить Python для всего сервера». Для приложений это иногда выглядит удобно, но для системы заканчивается поломкой пакетной инфраструктуры.

Облачный VDS-сервер в России

Аренда виртуальных серверов с моментальным развертыванием инфраструктуры от 195₽ / мес

Подробнее

Если вы часто тестируете разные версии Python, безопаснее делать это на отдельном VDS, а не на боевом сервере с рабочим APT. Так проще держать системное окружение предсказуемым и не ломать обновления.

С чего начать диагностику

Первая задача — понять, какой Python сейчас считается системным и существует ли модуль apt_pkg на диске.

Проверяем, на какой Python указывает система

ls -l /usr/bin/python3
python3 --version
which python3
readlink -f /usr/bin/python3

Если /usr/bin/python3 указывает на неожиданную версию, особенно установленную вручную, это уже сильная подсказка. Например, пакет python3-apt в конкретном релизе Ubuntu может быть собран под python3.10, а у вас системный python3 уже стал python3.12.

Ищем файл apt_pkg

find /usr/lib -name 'apt_pkg*.so' 2>/dev/null
find /usr/lib -name 'apt*.so' 2>/dev/null | grep python

Обычно модуль лежит в каталоге /usr/lib/python3/dist-packages/ и называется примерно так:

/usr/lib/python3/dist-packages/apt_pkg.cpython-310-x86_64-linux-gnu.so

Числа в имени файла важны: они показывают, под какую версию CPython собран модуль.

Проверяем пакет python3-apt

dpkg -l | grep python3-apt
dpkg -L python3-apt | grep apt_pkg
apt-cache policy python3-apt

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

Проверяем окружение и shebang

head -n 1 /usr/bin/add-apt-repository
env | grep -E '^PYTHON|^PATH='

Иногда проблему усиливают переменные окружения вроде PYTHONPATH или нетипичный PATH. На чистых серверах это редкость, но в автоматизации и кастомных скриптах такое встречается.

Самый частый сценарий: поломка после смены Python

Классическая ситуация выглядит так: администратор ставит новую версию Python ради приложения, а затем меняет системный симлинк:

ln -sf /usr/bin/python3.12 /usr/bin/python3

После этого пользовательский код может заработать, но модуль apt_pkg, собранный под старую версию интерпретатора, перестаёт импортироваться. В результате появляются ошибки ModuleNotFoundError и начинают падать служебные инструменты APT.

Правильный подход другой: новую версию Python ставят параллельно и вызывают явно, через нужный бинарник, venv или отдельное окружение. Системный python3 лучше не трогать.

Если вы как раз выносите приложения в отдельные окружения, может пригодиться материал про изоляцию сервисов и пулов на сервере: логика та же — разделять системное и прикладное окружение, а не смешивать всё в одном месте.

Безопасный путь восстановления

Лучше идти от самого штатного сценария к аварийным мерам. На продакшне это особенно важно.

Вариант 1. Вернуть штатный системный python3

Если вы вручную меняли /usr/bin/python3, самый правильный шаг — вернуть его к версии, предусмотренной дистрибутивом.

ls -l /usr/bin/python3*

Если вы знаете, что раньше система работала на python3.10, а потом была переключена на python3.12, верните прежний вариант:

ln -sf /usr/bin/python3.10 /usr/bin/python3

После этого проверьте импорт:

python3 -c 'import apt_pkg; print("OK")'

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

apt-get install --reinstall python3-apt

Вариант 2. Переустановить python3-apt

Если системный Python не трогали, но пакет повреждён, обычно помогает обычная переустановка:

apt-get update
apt-get install --reinstall python3-apt

Дальше снова проверяем импорт:

python3 -c 'import apt_pkg; print(apt_pkg.VERSION)'

Если ошибка осталась, значит дело, скорее всего, не в повреждении пакета, а в несовместимости версий Python.

Вариант 3. Переустановить пакет вручную через dpkg

Если обычный apt работает нестабильно, но dpkg ещё жив, можно использовать локальный пакет:

cat /etc/os-release
dpkg --print-architecture
ls -1 /var/cache/apt/archives/python3-apt*.deb
dpkg -i /var/cache/apt/archives/python3-apt*.deb

Здесь принципиально важно брать пакет строго для вашего релиза и архитектуры. Похожие по названию пакеты из другого релиза часто только усугубляют ситуацию.

Если после установки apt-get снова запускается, можно проверить зависимости:

apt-get -f install

Вариант 4. Временный симлинк на apt_pkg как аварийная мера

Этот совет часто встречается на форумах. Иногда он помогает, если проблема только в имени файла и ABI фактически совпадает:

cd /usr/lib/python3/dist-packages
ls -l apt_pkg*.so
ln -s apt_pkg.cpython-310-x86_64-linux-gnu.so apt_pkg.so

Но это не исправляет ситуацию, когда модуль собран под другую версию Python. Такой шаг допустим только как временная аварийная мера и только если вы понимаете, что версия интерпретатора и ABI действительно совпадают.

Если после такого симлинка импорт всё равно падает, не продолжайте подгонять имена файлов вручную. Возвращайтесь к проверке системного Python и установленного пакета python3-apt.

Как понять, какая версия Python должна быть системной

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

apt-cache show python3 | grep Depends
dpkg -s python3-minimal | grep Version
dpkg -l | grep '^ii' | grep python3

Дополнительно полезно посмотреть состав файлов пакетов:

dpkg -L python3-minimal
dpkg -L python3-apt

Нужно получить согласованную картину: пакет python3-minimal, бинарник /usr/bin/python3 и модуль apt_pkg должны относиться к одной системной ветке Python.

Что делать, если apt не запускается совсем

Даже если сломано почти всё, переустановка ОС обычно не нужна. Минимальный рабочий план такой:

1. Проверить, не подменён ли /usr/bin/python3.
2. Вернуть штатный интерпретатор, если его версия известна.
3. Найти файл apt_pkg*.so и убедиться, что он существует.
4. Переустановить python3-apt через локальный .deb и dpkg.
5. После восстановления проверить зависимости и недонастроенные пакеты.

Быстрая аварийная проверка может выглядеть так:

readlink -f /usr/bin/python3
find /usr/lib -name 'apt_pkg*.so' 2>/dev/null
dpkg -l | grep python3-apt
python3 -c 'import apt_pkg; print("OK")'

Если проблема началась после экспериментов с исходниками Python, дополнительно проверьте, нет ли перехвата через /usr/local/bin:

which -a python3
echo "$PATH"

Когда на сервере много автоматизации, полезно также держать под рукой отдельный материал про предсказуемый запуск сервисов через systemd: меньше нестандартного окружения — меньше сюрпризов с Python и путями.

Виртуальный хостинг для сайтов

Универсальное решение для создания и размещения сайтов любой сложности в Интернете от 95₽ / мес

Подробнее

Чего делать не стоит

Когда появляется такая ошибка, в сети часто советуют быстрые, но опасные решения. От них лучше отказаться:

• не копируйте apt_pkg*.so с другой машины без полного совпадения релиза и архитектуры;
• не меняйте системный python3 случайными симлинками «на глаз»;
• не удаляйте пакеты Python пачкой, не понимая зависимостей;
• не пытайтесь ставить python3-apt через pip;
• не смешивайте пакеты из Debian и Ubuntu между собой.

Отдельно про pip: python3-apt — это системный компонент дистрибутива, а не обычная библиотека для пользовательского окружения. Попытка починить его через Python-пакетный менеджер почти никогда не решает корневую причину.

Проверка после восстановления

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

python3 -c 'import apt_pkg; print("apt_pkg OK")'
apt-get update
apt-get check
dpkg --configure -a

Если обновление когда-то оборвалось посередине, команда dpkg --configure -a часто помогает аккуратно завершить настройку пакетов. А apt-get check покажет, остались ли сломанные зависимости.

Как избежать повторения проблемы

Почти каждый случай apt_pkg ImportError можно предотвратить простыми правилами:

• не меняйте /usr/bin/python3 вручную в Debian и Ubuntu;
• новые версии Python ставьте параллельно, без подмены системного интерпретатора;
• для приложений используйте venv или отдельные окружения;
• перед системными изменениями делайте снимок VM или резервную копию;
• не смешивайте сторонние репозитории без необходимости;
• после крупных обновлений проверяйте apt-get check.

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

Короткий runbook для администратора

1. Проверить, куда указывает /usr/bin/python3.
2. Найти apt_pkg*.so и посмотреть ABI-суффикс.
3. Убедиться, что установлен пакет python3-apt.
4. Вернуть штатный Python для вашего релиза.
5. Переустановить python3-apt.
6. Проверить apt-get update, apt-get check и dpkg --configure -a.

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

Итог

apt_pkg ImportError — это не загадочная поломка APT, а понятный симптом рассинхронизации между системным Python и пакетом python3-apt. Чаще всего проблема появляется после ручной замены Python или неаккуратного обновления. Самый надёжный путь — вернуть штатный интерпретатор дистрибутива и переустановить python3-apt, а не пытаться лечить сервер случайными симлинками.

Если идти по шагам — проверить /usr/bin/python3, найти apt_pkg, сверить версию Python и пакет, затем аккуратно восстановить систему, — проблема обычно решается быстро и без переустановки. А лучший способ не встретиться с ней снова — держать прикладной Python отдельно от системного.