Поиск
Ошибки

pip: error: subprocess-exited-with-error и Failed building wheel — пакет не собирается

pip скачал исходники пакета и запустил сборку, а сборка завершилась ошибкой. Настоящая причина — в строках между lines of output и end of output.

≈ 5 мин чтения3 шага
Содержание 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компилятора Csudo apt install build-essential
pg_configбиблиотеки PostgreSQL для psycopg2sudo apt install libpq-dev
mysql_config или mysqlclientбиблиотеки MySQL для mysqlclientsudo apt install pkg-config default-libmysqlclient-dev
ffi.hбиблиотеки libffisudo apt install libffi-dev
openssl/ssl.hбиблиотеки OpenSSLsudo 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"

Если команда ничего не вывела, пакет на месте.

Источники

Сверено 22 октября 2026 года.

Где проверить исправление. Если ошибка случилась на рабочем сайте, исправление спокойнее сначала проверить на отдельном тестовом VPS с Ubuntu, например в Timeweb Cloud Реклама. АО «ТАЙМВЭБ», ИНН 7810353960. erid: CQH36pWzJpoBWKF332yG5h2XQ4cVubfBmkvqAitFqcpzWs. Как зайти на него после заказа — в статье Как подключиться к VPS по SSH.

Что почитать дальше