Ошибка установки spaCy на Python 3.13: что делать

Почему pip install spacy падает на Python 3.13: несовместимость версий. Решение — перейти на Python 3.12 и поставить spaCy через conda или uv без сборок.

Установка spaCy на чистой машине и мгновенная ошибка ModuleNotFoundError могут сбить с толку, особенно когда pip install spacy раз за разом заканчивается неудачей с длинными логами сборки. Если у вас Python 3.13, это как раз тот случай: spaCy сейчас не поддерживает Python 3.13, поэтому установка откатывается к сборке низкоуровневых зависимостей из исходников и падает из‑за ошибок, связанных с компилятором.

Минимальный пример

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

import spacy as nlp_mod

Что на самом деле происходит

По состоянию на 17 мая 2025 года spaCy, судя по всему, не поддерживает Python 3.13. На таком интерпретаторе pip пытается удовлетворить цепочку зависимостей spaCy, подтягивая исходные дистрибутивы. В выводе видно, что загружается tar-архив для numpy (например, numpy-2.0.2.tar.gz) и запускается сборка на базе Meson. Затем сборка падает с сообщениями вроде Unknown compiler(s) и отсутствия инструментальной цепочки Visual Studio — отсюда subprocess-exited-with-error и metadata-generation-failed. Корень проблемы — версия Python, а не сам pip.

Ситуация и текущий статус отслеживаются здесь: Spacy installation on python 3.13 fails.

Решение

Переключитесь на Python 3.12 и установите spaCy там. Это можно сделать, создав окружение с Python 3.12 с помощью привычных инструментов — например, uv или conda (включая micromamba). После активации окружения 3.12 установка spaCy проходит штатно, и показанный выше минимальный скрипт импортируется без проблем.

Если вы изучаете поведение установки в других сценариях, у pip есть флаг --prefer-binary, который просит выбирать готовые колёса, когда они доступны, вместо локальной компиляции. Это не изменит совместимость spaCy с Python 3.13, но поможет избежать лишних сборок там, где колёса уже есть.

Рабочий код после смены окружения

Код приложения менять не требуется; важно запускать его под поддерживаемой версией интерпретатора.

import spacy as nlp_mod

Почему это важно

Совместимость версий между библиотеками и интерпретатором — первоочередной аспект в экосистеме Python. Если пакет не поддерживает вашу версию Python, pip часто переходит к сборке зависимостей из исходников, что в Windows требует нативного инструментария и обычно приводит к шумным и сбивающим с толку ошибкам. Понимание того, что ключевая проблема — поддержка версии, экономит время и избавляет от попыток настраивать компиляторы, которые вам на самом деле не нужны.

Выводы

Если pip install spacy на Python 3.13 падает, а в логах сборки мелькают Meson, компиляторы или metadata-generation-failed, не боритесь с тулчейном. Для spaCy на 17 мая 2025 года используйте Python 3.12 — через uv или conda/micromamba — и импорт заработает как задумано. Следите за связанным тикетом на GitHub, чтобы узнать о поддержке Python 3.13. Разбираясь с похожими проблемами, сначала проверяйте, какие версии Python поддерживает пакет, и уже потом выбирайте или фиксируйте интерпретатор; это самый быстрый путь к чистой установке.