pip: Failed building wheel — требуется Microsoft Visual C++ 14.0

#Почему pip собирает пакет

Если для вашей версии Python и платформы нет готового бинарного колеса (wheel) на PyPI, pip скачивает исходный код и компилирует C/C++ расширения. Для этого на Windows нужен компилятор Microsoft C++ (MSVC). Ошибка означает, что его нет. Но чаще всего собирать ничего не нужно: достаточно обновить pip, выбрать версию Python, для которой есть колёса (обычно на один-два релиза старше самой новой), или взять готовое колесо.

#Типичные причины

#Порядок

1. Обновите pip, setuptools и wheelВ Windows откройте «Пуск» → «Терминал» или PowerShell, активируйте среду своего проекта (если используется). Выполните py -m pip --version, затем py -m pip install --upgrade pip setuptools wheel. Здесь py — установленный диспетчер Python в Windows; если он отсутствует, используйте путь к тому python.exe, который выполняет проект. Обновление иногда помогает получить готовый пакет, но не заменяет компилятор, если исходная сборка обязательна.
2. Проверьте версию Python: для новых пакетов колёса выходят с задержкойВ том же терминале выполните py --version, py -m pip --version и py -c "import platform; print(platform.machine())". Сверьте версию, разрядность и архитектуру с разделом «Requires Python» и файлами пакета на pypi.org/project/имя_пакета/. Если версия Python слишком новая или старая, сначала создайте отдельное виртуальное окружение на поддерживаемой версии, не удаляя действующую среду проекта.
3. Установите с флагом --only-binary :all:, чтобы pip не пытался собиратьЧтобы проверить, есть ли готовый пакет для вашей версии Python, в активной среде выполните py -m pip install --only-binary=:all: имя_пакета (замените имя). Ключ запрещает компиляцию. Если видите No matching distribution found, готового совместимого колеса, возможно, нет в выбранном источнике; это не доказательство, что пакет совсем отсутствует. Удалите --only-binary только после выяснения причин и оценки требований сборки.
4. Попробуйте более старую версию пакета, где есть колесоОткройте страницу выпусков пакета на PyPI и проверьте, какие версии поддерживают вашу версию Python и архитектуру. Если предыдущий поддерживаемый выпуск действительно имеет готовое колесо, установите точную версию командой py -m pip install "имя_пакета==X.Y.Z", подставив установленное по документации число версии. Учтите зависимости проекта и требования безопасности; не откатывайтесь на уязвимую версию наугад.
5. Используйте окружение conda/mambaЕсли пакет недоступен на PyPI в готовом виде, проверьте, публикуется ли он в conda-forge. Этот способ альтернативен pip, а не последовательный дополнительный шаг. В терминале установленного Miniforge создайте отдельную среду: conda create -n testpkg python=3.12, затем conda activate testpkg и conda install -c conda-forge имя_пакета (версию Python и пакет выберите по совместимости). Проверьте импорт в этой среде; не смешивайте среды без необходимости.
6. Если сборка необходима, установите Build Tools и компонент «РазработкаЕсли ошибка явно требует MSVC, а готового колеса нет, откройте официальный сайт Visual Studio → «Загрузки» → «Средства для сборки Visual Studio», скачайте Build Tools. В установщике отметьте рабочую нагрузку «Разработка классических приложений на C++» (Desktop development with C++), включая MSVC и Windows SDK. Для установки понадобятся права администратора и свободное место. Избегайте случайных сайтов с отдельным cl.exe.
7. Выберите способ в командной строке или терминалеЕсли предыдущие действия не помогли, прочитайте назначение каждого варианта ниже. Не выполняйте их все подряд: выбирайте только соответствующий вашей ситуации.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1Версии Python, pip и платформа

   Windows · Командная строка (CMD)КомандаКопировать всёВыделить

   Версии Python, pip и платформа

   python --version

   python -m pip --version

   python -c "import platform, struct; print(platform.machine(), struct.calcsize('P')*8, 'bit')"

   Вариант 2Обновить инструменты

   Windows · Командная строка (CMD)КомандаКопировать всёВыделить

   Обновить инструменты

   python -m pip install --upgrade pip setuptools wheel

   Вариант 3Вместо numpy подставьте фактический пакет; если используется venv, лучше python -m pip

   Windows · Командная строка (CMD)КомандаКопировать всёВыделить

   Вместо numpy подставьте фактический пакет; если используется venv, лучше python -m pip

   # В Windows, в терминале нужного Python/venv

   py -m pip install --only-binary=:all: numpy

   Вариант 4Посмотреть, какие колёса есть для пакета (теги)

   Windows · Командная строка (CMD)КомандаКопировать всёВыделить

   Посмотреть, какие колёса есть для пакета (теги)

   python -m pip download --only-binary :all: --no-deps -d wheels_check numpy

   python -m pip debug --verbose | findstr /i "compatible"

   Вариант 5Заглушку не вводить буквально; заменить именем, указанным в ошибке pip

   Windows · Командная строка (CMD)КомандаКопировать всёВыделить

   Заглушку не вводить буквально; заменить именем, указанным в ошибке pip

   # Вместо имя_пакета укажите имя настоящей зависимости; запускать из среды разработчика Visual Studio

   py -m pip install имя_пакета -v

   Вариант 6Установка Build Tools через winget (затем в установщике отметьте «Разработка классических приложений на C++»)

   Windows · Командная строка (CMD)КомандаКопировать всёВыделить

   Установка Build Tools через winget (затем в установщике отметьте «Разработка классических приложений на C++»)

   winget install Microsoft.VisualStudio.2022.BuildTools

8. Читайте ошибку компиляции: иногда не хватает стороннего заголовка, а неЕсли в журнале остаётся ошибка сборки, прокрутите вывод выше строки Failed building wheel и найдите первую конкретную ошибку: fatal error C1083 означает отсутствующий заголовочный файл, link.exe — проблемы линковщика, unsupported Python version — несовместимую версию. Сохраните название пакета, версию Python, команду, первые строки ошибки и обратитесь к документации пакета. Установка MSVC не исправит все ошибки сборки.

#Виртуальные окружения

Создавайте отдельное окружение для проекта: python -m venv .venv и .venv\Scripts\activate. Так вы избежите конфликтов версий и сможете выбрать подходящую версию Python для зависимостей. Проверьте requirements.txt: пакеты с жёсткой фиксацией старых версий могут не иметь колёс для вашей версии Python.