Как исправить ошибку 'No module named distutils' в Python 3.12+

kirilljsx

Если вы работаете с Python 3.12 или новее, вероятно, уже встречались с ошибкой ModuleNotFoundError: No module named 'distutils'. Эта проблема появляется при попытке установить пакеты или запустить код, который зависит от удалённого модуля distutils. Разберёмся, почему это происходит и как быстро это исправить.

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

Почему distutils был удалён

Модуль distutils долгое время использовался для сборки и установки дополнительных модулей Python. Однако со временем сообщество разработчиков понимало, что модуль устарел и имеет архитектурные проблемы. Вместо него появился более современный и гибкий setuptools.

Начиная с Python 3.12, distutils был полностью удалён из стандартной библиотеки. Это означает, что любой импорт вроде import distutils или from distutils.core import setup будет вызывать ошибку. Многие популярные библиотеки (TensorFlow, PyMC3, речевые модули) всё ещё содержат код, который пытается использовать distutils при импорте или установке.

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

Основное решение: установка setuptools

Первый и самый надёжный способ исправить проблему — установить пакет setuptools. Этот пакет предоставляет функциональность, которая раньше была в distutils, и большинство современных пакетов используют его вместо встроенного модуля.

Установка зависит от вашей операционной системы. Если у вас Linux (Ubuntu, Debian или производные), используйте пакетный менеджер. На macOS и Windows проще всего работать через pip. Убедитесь, что у вас достаточно прав, и выполните нужную команду для вашей системы.

Для Linux (Ubuntu/Debian):

sudo apt install python3-setuptools

Для macOS и Windows через pip:

pip install setuptools

Если вы используете более новые инструменты управления пакетами (например, uv), команда будет:

uv add setuptools

После установки setuptools большинство пакетов, которые зависят от distutils, должны работать без дополнительных изменений. Проверьте, пропала ли ошибка, попробовав снова импортировать нужный вам модуль.

Когда setuptools недостаточно

Иногда даже после установки setuptools ошибка не исчезает. Это может произойти по нескольким причинам. Во-первых, версия setuptools, установленная в вашей системе через пакетный менеджер, может быть старой и несовместимой с Python 3.12. Во-вторых, некоторые пакеты напрямую импортируют distutils вместо использования setuptools.

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

Явный импорт setuptools.dist: добавьте import setuptools.dist в начало вашего файла перед другими импортами. Это заставляет Python использовать версию distutils из setuptools вместо встроенной (которой уже нет).
Обновите версию setuptools: убедитесь, что у вас установлена последняя версия. Выполните pip install --upgrade setuptools.
Проверьте версию пакета, вызывающего ошибку: некоторые популярные библиотеки (как PyMC3) устарели и не поддерживают Python 3.12. Попробуйте обновить пакет или переойти на его более новую версию (например, PyMC вместо PyMC3).
Обойтись без системных пакетов: на Ubuntu 24.04 и Linux Mint 22 пакетный менеджер может установить старую версию setuptools. В этом случае лучше использовать pip с флагом --break-system-packages (на свой риск) или установить Python через инструменты вроде pyenv.

Практический чек-лист

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

Убедитесь, что вы действительно используете Python 3.12 или новее (команда: python --version)
Установите или обновите setuptools: pip install --upgrade setuptools
Попробуйте импортировать нужный вам пакет
Если ошибка остаётся, добавьте import setuptools.dist в начало файла
Проверьте, доступна ли новая версия проблемного пакета (обновите через pip install --upgrade имя_пакета)
Если ничего не помогает — временно переключитесь на Python 3.11 или старше, пока разработчики пакета не обновят его

Разные сценарии и их решения

Сценарий	Решение	Примечание
Первичная установка пакета на Python 3.12	`pip install setuptools`, затем переустановить пакет	Самое простое решение
PyMC3, TensorFlow или другие старые библиотеки	Обновиться на новую версию (PyMC 5+, TensorFlow с поддержкой 3.12)	Разработчики должны были обновить код
Собственный код использует distutils	Замените на setuptools в setup.py	Измените `from distutils.core import setup` на `from setuptools import setup`
Linux с системным Python 3.12	Установите python3-full или используйте виртуальное окружение	Системный Python может быть несовместим
Работаете в контейнере или на сервере	Добавьте `RUN apt install python3-setuptools` в Dockerfile	Убедитесь, что пакет установлен на этапе сборки

Долгосрочная стратегия

Эта проблема будет актуальна некоторое время, так как в мире Python огромное количество legacy-кода, который никто не обновляет. Но понимание её природы поможет вам действовать уверенней.

Если вы разработчик и пишете свои пакеты, уже сейчас переходите на setuptools вместо distutils. Обновите свои setup.py файлы, чтобы использовать setuptools вместо distutils.core. Это не сложно, но защитит ваш код от проблем в будущем. Самые современные проекты вообще переходят на pyproject.toml и инструменты вроде build, полностью отказываясь от setup.py.

Для обычных пользователей совет простой: не зацикливайтесь на этой ошибке, почти всегда помогает установка setuptools. Если работаете на работе и не можете устанавливать системные пакеты — создайте виртуальное окружение Python 3.11 или используйте Docker. Это будет надёжнее и безопаснее, чем обходить ограничения системы.