Как исправить No module named 'manim' в Python при запуске через python3 и uv

Разбираем ошибку No module named 'manim' в Python на Arch Linux и других системах: причины несоответствия окружений при установке через uv и пошаговое решение.

Сообщение No module named 'manim' при запуске скрипта через python3, в то время как manim -pqh работает, — классический признак несоответствия окружений. Командная утилита видит Manim, а ваш интерпретатор Python — нет. В Arch Linux и любых других дистрибутивах корневая причина обычно сводится к тому, как Manim был установлен с помощью uv и какой именно Python выполняет ваш код.

Минимальный пример, который падает под python3

Следующий фрагмент достаточен, чтобы воспроизвести проблему, когда Manim отсутствует в sys.path интерпретатора:

from manim import *
class BaseCircleScene(Scene):
    def construct(self):
        shape_obj = Circle()
        shape_obj.set_fill(BLUE, opacity=0.8)
        label_obj = Text("Circle").next_to(shape_obj, DOWN)
        self.play(Write(shape_obj), Write(label_obj))
        self.wait(2)

Запуск через CLI Manim работает как ожидается:

manim -pqh demo.py BaseCircleScene

А прямой вызов интерпретатора не может импортировать пакет:

python3 demo.py

Почему это происходит

С uv есть два разных способа установки Manim, и они приводят к разным моделям запуска. Установка через uv init myproj, затем cd myproj && uv add manim помещает Manim в виртуальное окружение конкретного проекта. Установка через uv tool install manim настраивает Manim как глобальный инструмент. Эти подходы во время выполнения не взаимозаменяемы.

Когда Manim установлен в проект, управляемый uv, пакет находится внутри виртуального окружения этого проекта. Если вы запускаете скрипт системным интерпретатором, он не увидит site-packages проекта, и вы получите No module named 'manim'. При этом CLI Manim может работать, потому что запускается из окружения, где Manim установлен. Быстрая проверка вроде uv pip show manim, которая возвращает “Package(s) not found for: manim”, вместе с sys.path, содержащим только системные пути, указывает на то, что вы находитесь вне окружения, куда установлен Manim. Это укладывается в типичный сценарий: одна установка Python использовалась для установки пакета, а другая — для запуска кода.

Как это исправить

Если Manim был добавлен в проект uv, используйте интерпретатор самого проекта. Visual Studio Code может выбрать его автоматически; если нет — укажите вручную. В командной строке проверьте, какой Python используется:

which python3

Если вывод похож на .venv/bin/python3, вы находитесь в окружении проекта. Если путь ведёт на /usr/bin/python3 или что-то похожее, активируйте окружение проекта или запускайте напрямую через uv:

source .venv/bin/activate
python3 demo.py

или

uv run demo.py

Если Manim установлен как глобальный инструмент uv, редактор кода не распознает это окружение автоматически. В документации описано, как настроить редактор, чтобы import manim корректно находился при использовании uv global.

Необязательный диагностический фрагмент

Чтобы понять, какой интерпретатор исполняет ваш скрипт и что он видит для импорта, выведите это в самом начале файла:

import sys
print(sys.executable)
print(sys.path)

Если видны только системные пути, значит, используется не то проектное окружение, где установлен Manim.

Правильный запуск примера

Оставьте сцену без изменений — правки кода не нужны. Запускайте её из подходящего окружения: либо активируйте виртуальное окружение проекта и вызовите python3, либо позвольте uv выбрать корректный интерпретатор за вас:

uv run demo.py

Если удобнее, можно по‑прежнему рендерить через CLI:

manim -pqh demo.py BaseCircleScene

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

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

Выводы

Определитесь, вы используете проект uv или глобальный инструмент uv, и придерживайтесь этого выбора и при установке, и при запуске. Для проектов предпочтительны uv init и uv add manim, затем запускайте код через интерпретатор проекта, активируйте .venv или используйте uv run. В VSCode явно выберите тот же интерпретатор. Если выбрали глобальный инструмент, следуйте документации и настройте редактор так, чтобы import manim разрешался корректно. Как только все укажет на один и тот же Python, ошибка No module named 'manim' исчезнет.