Ошибка Preparing metadata (pyproject.toml) ... error возникает в момент, когда pip пытается собрать пакет из исходного кода, потому что готовой скомпилированной сборки (wheel) для вашей версии Python или платформы не нашлось. Чаще всего это происходит при установке библиотек с компилируемыми расширениями — например, numpy, pandas, psycopg2 или pillow — на новой версии Python, под которую авторы пакета ещё не опубликовали бинарные сборки.
Текст после строки Preparing metadata (pyproject.toml) ... did not run successfully обычно содержит реальную причину: отсутствующий компилятор, несовместимость версий или устаревший setuptools. Ниже разберём, как прочитать этот лог и какие шаги помогают в каждом конкретном случае.
Почему возникает ошибка preparing metadata pyproject.toml
Файл pyproject.toml — это современный стандарт описания сборки Python-пакета. Когда pip не находит готовый wheel-файл, он скачивает исходники и запускает систему сборки, указанную в этом файле. Если сборка падает, вы видите именно эту ошибку.
Типичные причины:
- 🔧 Несовместимость версий — пакет не поддерживает вашу версию Python (слишком новую или слишком старую).
- 🛠️ Отсутствует компилятор — на Windows нет Microsoft C++ Build Tools, на Linux — пакетов
gccиpython3-dev. - 📦 Устаревший pip или setuptools — старые версии не понимают новые форматы сборки.
- 🌐 Проблемы с сетью или зеркалом PyPI — скачался повреждённый архив исходников.
- 🧩 Конфликт зависимостей — требуемая версия библиотеки несовместима с уже установленными пакетами.
Шаг 1. Прочитайте полный текст ошибки
Не ограничивайтесь последней строкой. Прокрутите вывод терминала вверх — над строкой did not run successfully находится блок с реальной причиной. Ищите упоминания конкретных файлов, компилятора или фразы вроде error: Microsoft Visual C++ 14.0 or greater is required.
Чтобы получить максимально подробный лог, повторите установку с флагом подробного вывода:
pip install имя_пакета -v⚠️ Внимание: не копируйте первое попавшееся решение из интернета, не прочитав свой лог. Одна и та же строка Preparing metadata (pyproject.toml) error скрывает десятки разных причин, и «универсального» исправления не существует.
Шаг 2. Обновите pip, setuptools и wheel
Устаревший инструментарий сборки — одна из самых частых причин сбоя. Обновление занимает меньше минуты и решает проблему, если пакет использует новые возможности формата pyproject.toml.
python -m pip install --upgrade pip setuptools wheelПосле обновления повторите установку нужного пакета. Если ошибка сохранилась — переходите к следующим шагам.
☑️ Базовая диагностика ошибки
Шаг 3. Проверьте совместимость версии Python
Если вы установили свежий релиз Python, а авторы пакета ещё не выпустили под него сборки, pip вынужден компилировать из исходников — и часто безуспешно. Проверьте свою версию командой python --version и сверьте её с поддерживаемыми версиями на странице пакета в PyPI (раздел «Requires: Python»).
Практический выход — установить более старую, стабильно поддерживаемую версию Python и собрать проект под ней. Это самый частый сценарий: пакет просто не имеет готовой сборки под только что вышедший Python.
Шаг 4. Установите инструменты компиляции
Если лог указывает на отсутствие компилятора, сборку из исходников нужно обеспечить инструментами. На Windows установите Microsoft C++ Build Tools с официального сайта Microsoft — в установщике отметьте рабочую нагрузку разработки на C++. На Debian/Ubuntu обычно помогает установка пакетов разработки:
sudo apt install build-essential python3-devДля отдельных библиотек могут понадобиться дополнительные системные зависимости — например, заголовки libpq для psycopg2 или libjpeg для старых версий Pillow. Точный список зависит от конкретного пакета, поэтому сверяйтесь с его официальной документацией по установке.
⚠️ Внимание: не устанавливайте компиляторы и dev-пакеты из неофициальных источников. Скачивайте Build Tools только с сайта Microsoft, а системные пакеты — только из штатных репозиториев вашего дистрибутива.
Шаг 5. Альтернативные способы установки
Иногда проще обойти сборку из исходников, чем чинить её. Рабочие варианты:
- 📌 Зафиксировать более старую версию пакета —
pip install имя_пакета==X.Y, где X.Y — версия, для которой существует wheel под вашу платформу. - 🐍 Использовать conda — дистрибутивы Anaconda/Miniconda поставляют предсобранные пакеты со своими бинарными зависимостями.
- 🧪 Чистое виртуальное окружение —
python -m venv venvисключает конфликты с уже установленными библиотеками. - 🗜️ Неофициальные wheel-сборки — вариант на крайний случай; используйте только источники, которым доверяете.
Сравнение причин и решений
| Симптом в логе | Вероятная причина | Решение |
|---|---|---|
| Microsoft Visual C++ 14.0 is required | Нет компилятора в Windows | Установить Build Tools |
| Python.h: No such file or directory | Нет заголовков Python в Linux | Установить python3-dev |
| No matching distribution found | Нет сборки под вашу версию Python | Сменить версию Python или пакета |
| Ошибка в setuptools / backend | Устаревший инструментарий | Обновить pip, setuptools, wheel |
| Конфликт зависимостей | Несовместимые версии пакетов | Чистое виртуальное окружение |
Почему ошибка появляется в Docker-контейнерах
Минимальные образы вроде python:slim или alpine не содержат компиляторов и заголовков. В Alpine дополнительно используется musl вместо glibc, поэтому многие wheel-файлы с PyPI там не подходят, и pip пытается собирать из исходников. Решение — использовать полный образ python:3.x, добавить в Dockerfile установку build-зависимостей или выбрать пакеты с musllinux-сборками.
Часто задаваемые вопросы
Что означает строка «Preparing metadata (pyproject.toml) ... did not run successfully»?
Это означает, что pip не смог выполнить этап подготовки метаданных при сборке пакета из исходного кода. Сама по себе эта строка — только признак; реальная причина указана выше в логе установки.
Помогает ли обновление pip решить эту ошибку?
Иногда да — если сбой вызван устаревшим pip или setuptools, не поддерживающим формат сборки пакета. Но если причина в отсутствии компилятора или несовместимости версий Python, одного обновления недостаточно.
Можно ли установить пакет без сборки из исходников?
Да, если для вашей платформы существует готовый wheel-файл. Используйте флаг --only-binary :all:, чтобы pip не пытался компилировать. Если сборки нет — попробуйте более старую версию пакета или другую версию Python.
Почему ошибка возникает только на новой версии Python?
Авторам пакетов нужно время, чтобы выпустить бинарные сборки под свежий релиз интерпретатора. До этого момента pip получает только исходники, и их компиляция может завершаться ошибкой. Практичный вариант — остаться на предыдущей стабильной версии Python.
Ошибка возникает внутри Docker — что делать?
Проверьте базовый образ: минимальные образы лишены компиляторов и заголовков. Перейдите на полный образ python:3.x или добавьте в Dockerfile установку необходимых build-зависимостей до вызова pip install.