pip: error: subprocess-exited-with-error и Failed building wheel — пакет не собирается
pip скачал исходники пакета и запустил сборку, а сборка завершилась ошибкой. Настоящая причина — в строках между lines of output и end of output.
Содержание 7
Как выглядит ошибка
Building wheels for collected packages: example-pkg
…
error: subprocess-exited-with-error
× Building wheel for example-pkg (pyproject.toml) did not run successfully.
│ exit code: 1
╰─> [40 lines of output]
…
[end of output]
note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed building wheel for example-pkg
Failed to build example-pkg
ERROR: Could not build wheels for example-pkg, which is required to install pyproject.toml-based projectsТак пишет pip 24.0 из Ubuntu 24.04. В pip 25.1.1 из Ubuntu 26.04 последняя строка другая:
ERROR: Failed to build installable wheels for some pyproject.toml based projects (example-pkg)Тексты сверены с исходным кодом pip 24.0 из пакетов Ubuntu 24.04 и pip 25.1.1 из пакетов Ubuntu 26.04.
Wheel — готовая сборка пакета. Если для вашей версии Python и процессора её нет, pip скачивает исходники и собирает пакет на сервере. Пакетам с кодом на C для этого нужны компилятор и заголовочные файлы библиотек, а на свежем сервере их может не быть.
Если сборка упала ещё раньше, в строке с × будет Preparing metadata (pyproject.toml) did not run successfully, а в конце — error: metadata-generation-failed. Причину ищут так же.
Шаг 1. Найдите причину в выводе
Команды на этой странице вводятся на сервере: подключитесь к нему по SSH (как подключиться) и набирайте их в том же окне. Команды pip на этой странице вводятся во включённом окружении venv: в начале строки ввода видно (venv). Как его создать и включить — в разделе Виртуальное окружение venv.
Строки внутри блока — вывод самой сборки, pip их не меняет. Чтобы прочитать их целиком, повторите установку с записью в файл:
pip install example-pkg 2>&1 | tee pip.logНайдите строки со словом error (команда grep):
grep -n -i "error" pip.log | head -20Смотрите первые строки с error внутри блока: в них или рядом с ними — причина. Файл pip.log можно пролистать командой less pip.log (как смотреть файлы).
Шаг 2. Поставьте, чего не хватает
Что искать в строках сборки и что ставить:
| Что упоминается в выводе | Чего не хватает | Что поставить |
|---|---|---|
| файл Python.h | заголовков Python для сборки | sudo apt install python3-dev |
| gcc, cc или x86_64-linux-gnu-gcc | компилятора C | sudo apt install build-essential |
| pg_config | библиотеки PostgreSQL для psycopg2 | sudo apt install libpq-dev |
| mysql_config или mysqlclient | библиотеки MySQL для mysqlclient | sudo apt install pkg-config default-libmysqlclient-dev |
| ffi.h | библиотеки libffi | sudo apt install libffi-dev |
| openssl/ssl.h | библиотеки OpenSSL | sudo apt install libssl-dev |
Если система спросит пароль, введите пароль своего пользователя на сервере. Символы при вводе не видны — так и должно быть: наберите пароль и нажмите Enter. На вопрос Do you want to continue? [Y/n] нажмите Y и Enter. Пакеты python3-dev и build-essential нужны сборке любых пакетов с кодом на C, их можно поставить сразу:
sudo apt install python3-dev build-essentialЗатем повторите pip install в том же окружении.
Шаг 3. Если сборка нужна из-за старой версии
Если в requirements.txt записана старая версия пакета, готовой сборки под ваш Python у неё может не быть, и pip начинает собирать из исходников. Посмотрите, какой Python в окружении:
python --versionОткройте страницу пакета на pypi.org, раздел Download files: в именах файлов .whl указана версия Python, например cp312 — для Python 3.12, cp314 — для 3.14. Если для вашей версии файлы есть только у более новой версии пакета, поднимите номер в requirements.txt и проверьте приложение. Файлы с abi3 в имени подходят и к более новым версиям Python.
Как проверить
Повторите установку. В конце должна быть строка Successfully installed и имя пакета. Проверьте, что модуль загружается — вместо example_pkg подставьте имя для import:
python -c "import example_pkg"Если команда ничего не вывела, пакет на месте.
Источники
- Исходный код pip 24.0: exceptions.py — блок subprocess-exited-with-error, строки lines of output, end of output и note, metadata-generation-failed.
- Исходный код pip 24.0: operations/build/wheel.py — Building wheel и Failed building wheel.
- Исходный код pip 24.0: wheel_builder.py — Failed to build и отступ строк при сборке.
- Исходный код pip 24.0: commands/install.py — Could not build wheels.
- Исходный код pip 25.1.1: commands/install.py — Failed to build installable wheels.
- Документация mysqlclient — какие пакеты нужны для сборки в Ubuntu.
- Документация psycopg2: Build prerequisites — pg_config и libpq-dev.
Сверено 22 октября 2026 года.