Неудачная компиляция wheel: действия разработчика

Раздел: Разработка на Python -> Ошибки сборки

Основной способ: установка системных зависимостей для компиляции

Как исправить ошибку сборки wheel при установке пакета, требующего компиляции?

Наиболее частая причина ошибки - отсутствие в системе компиляторов и заголовочных файлов, необходимых для сборки C-расширений. Решение зависит от операционной системы.

Для Linux (Ubuntu/Debian):

sudo apt update
sudo apt install build-essential python3-dev libssl-dev libffi-dev

Python failed building wheel (ошибка сборки wheel)

После этого установка пакета через pip должна пройти успешно.

Типичные проблемы:

Если ошибка осталась, возможно, требуется установить дополнительные пакеты, специфичные для библиотеки (например, libjpeg для Pillow, libxml2 для lxml).
На Windows часто требуется Microsoft Visual C++ Build Tools или Visual Studio Community Edition.
На macOS - Xcode Command Line Tools (xcode-select --install).

Для Windows:

# Установка Build Tools для Visual Studio 2022 с компонентом "Разработка на C++"
# Скачайте с https://visualstudio.microsoft.com/ru/downloads/#build-tools-for-visual-studio-2022
# Или установите Visual Studio с соответствующей нагрузкой

Для macOS:

xcode-select --install

Решение 1: Использование предварительно собранных (бинарных) колес

Как избежать сборки пакета из исходных кодов?

Pip может загружать бинарные wheels, если они доступны. Принудительно отключить сборку можно через --only-binary:

pip install --only-binary :all: numpy

Если требуется установить и зависимости с бинарниками, можно указать pip install --only-binary :all: package. Однако это не сработает, если бинарного колеса нет для данной платформы/версии Python.

Возможные проблемы:

Если бинарное колесо отсутствует, pip выдаст ошибку "No matching distribution found". В этом случае нужно искать wheel на PyPI вручную (раздел Download files) или использовать другие методы.

Решение 2: Установка конкретной версии компилятора для Windows

Что делать, если ошибка указывает на отсутствие "cl.exe" или "Visual C++ 14.0"?

Некоторые пакеты (например, scikit-learn, cryptography) требуют определенную версию Visual Studio. Установите Microsoft Build Tools for Visual Studio 20XX с компонентом "C++ Build Tools". Затем настройте окружение через:

"%ProgramFiles(x86)%\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
pip install package

Или используйте Visual Studio Installer, выбрав рабочую нагрузку "Разработка классических приложений на C++".

Проблема:

После установки Build Tools может потребоваться перезапуск терминала. Также убедитесь, что используется 64-разрядная версия, если Python 64-bit.

Решение 3: Установка пакета через conda

Как установить пакет без компиляции, используя менеджер пакетов conda?

Conda предоставляет бинарные сборки для многих научных пакетов. Пример:

conda install numpy pandas scikit-learn

Conda сама разрешает зависимости и устанавливает совместимые версии библиотек, что часто избегает ошибок сборки.

Недостатки:

Не все пакеты доступны в conda (особенно не из Anaconda репозитория).
Требуется установка Anaconda или Miniconda.
Смешивание conda и pip может привести к конфликтам.

Решение 4: Установка старой версии пакета

Как временно обойти ошибку установки последней версии?

Иногда более старые версии пакетов уже имеют бинарные wheels для вашей платформы или не требуют таких современных компиляторов. Попробуйте:

pip install numpy==1.19.5

Используйте pip install package== и посмотрите список доступных версий на PyPI.

Предупреждение:

Старые версии могут иметь уязвимости или несовместимости с другими пакетами. Использовать такой подход стоит временно, пока не будет найдено полноценное решение.

Решение 5: Установка зависимостей, указанных в документации пакета

Где найти перечень библиотек, необходимых для сборки?

Многие пакеты (например, Pillow, lxml, psycopg2) требуют системные библиотеки. Перед pip install ознакомьтесь с документацией. Для Pillow на Ubuntu:

sudo apt install libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk

Для psycopg2: установите libpq-dev.

Проблема:

Иногда документация устарела или предоставляет инструкции только для одной ОС. Полезно искать ошибку в интернете по названию пакета и своей системы.

Расширенные примеры и результаты

Пример 1: Ubuntu - от ошибки к успешной установке

Исходная ситуация: попытка установить numpy.

Пример

$ pip install numpy
Collecting numpy
  Downloading numpy-1.26.2.tar.gz (15.8 MB)
  ...
  Building wheel for numpy (setup.py) ... error
  ERROR: Failed building wheel for numpy
  Failed to build numpy
  ERROR: Could not build wheels for numpy, which is required to install pyproject.toml-based projects

Устанавливаем зависимости:

Пример

$ sudo apt update && sudo apt install build-essential python3-dev -y

Результат (после pip install):

$ pip install numpy
Collecting numpy
  Using cached numpy-1.26.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Successfully installed numpy-1.26.2

Теперь pip использует бинарный wheel.

Пример 2: Windows - установка cryptography с Visual C++

Ошибка:

Пример

C:\> pip install cryptography
  error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools"

После установки Build Tools и выполнения vcvars64.bat:

Пример

C:\> "%ProgramFiles(x86)%\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
C:\> pip install cryptography
Collecting cryptography
  Downloading cryptography-41.0.7-cp312-cp312-win_amd64.whl
Successfully installed cryptography-41.0.7

Обратите внимание: после настройки окружения pip загружает бинарный wheel, сборка не требуется.

Пример 3: Использование --only-binary для пакета без бинарного колеса

Пример

$ pip install --only-binary :all: pycairo
  ERROR: Could not find a version that satisfies the requirement pycairo (from versions: none)
  ERROR: No matching distribution found for pycairo

Это означает, что для вашей платформы бинарного колеса нет. Нужно установить системные зависимости (в Ubuntu: libcairo2-dev) и повторить без --only-binary.

$ sudo apt install libcairo2-dev
$ pip install pycairo
Successfully installed pycairo-1.26.0

Пример 4: Установка пакета через conda

Пример

$ conda install -c conda-forge opencv
Collecting package metadata: done
Solving environment: done
...
Downloading and Extracting Packages: done
Preparing transaction: done
Verifying transaction: done
Executing transaction: done

Все бинарные зависимости устанавливаются автоматически.

Пример 5: Откат к старой версии, если последняя не собирается

Пример

$ pip install pandas==1.3.5
Collecting pandas==1.3.5
  Downloading pandas-1.3.5-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Successfully installed pandas-1.3.5

Версия 1.3.5 имеет предкомпилированный wheel, а последняя версия 2.1.4 на этой платформе требовала сборки. После временного использования старой версии можно искать решение для новой.

Ошибка сборки wheel - comments

Python failed building wheel (python)