Resolve No module named 'manim' in python3 by using the correct uv environment or Manim CLI

Fix No module named 'manim' when python3 fails but manim -pqh works. Learn uv project vs global tool, select the right Python and venv to resolve imports.

Seeing No module named 'manim' when running a script with python3, while manim -pqh works, is a classic environment mismatch. The command-line tool finds Manim, your Python interpreter does not. On Arch Linux or any other distro, the root cause usually boils down to how Manim was installed with uv and which Python is actually executing your code.

Minimal example that fails under python3

The following snippet is enough to reproduce the issue when Manim isn’t on the interpreter’s 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)

Invoking the Manim CLI works as expected:

manim -pqh demo.py BaseCircleScene

But calling the interpreter directly fails to import the package:

python3 demo.py

Why this happens

There are two distinct ways to install Manim using uv, and they lead to different execution models. Installing with uv init myproj followed by cd myproj && uv add manim places Manim into a project-specific virtual environment. Installing with uv tool install manim sets up Manim as a global tool. These two approaches are not interchangeable at runtime.

When Manim is installed into a uv-managed project, the package lives inside that project’s virtual environment. If you run your script with the system interpreter, it won’t see the project’s site-packages and you’ll get No module named 'manim'. In contrast, the Manim CLI can work because it runs from an environment where Manim is present. A quick check like uv pip show manim returning “Package(s) not found for: manim” together with a sys.path that only lists system locations indicates that you are not inside the environment where Manim was installed. This lines up with the usual cause: one Python installation was used to install the package, a different one is used to run the code.

How to fix it

If Manim was added to a uv project, use the project’s interpreter. Visual Studio Code can pick it automatically; otherwise, select it manually. On the command line, verify which Python you’re using:

which python3

If the output is something like .venv/bin/python3, you are inside the project environment. If it points to /usr/bin/python3 or similar, activate the project’s environment or run through uv directly:

source .venv/bin/activate
python3 demo.py

or

uv run demo.py

If Manim was installed as a uv global tool, the code editor will not automatically detect that tool environment. The documentation explains how to configure your editor so that import manim resolves correctly when using uv global.

Optional diagnostic snippet

To confirm which interpreter is running your script and what it can import, print these at the very start of your file:

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

If you see only system paths, you’re not using the project environment where Manim resides.

Running the example correctly

Keep the scene as-is; there is no code change required. Run it from the right environment either by activating the project’s virtualenv and invoking python3, or by letting uv use the correct interpreter for you:

uv run demo.py

You can still render via the CLI if you prefer:

manim -pqh demo.py BaseCircleScene

Why this matters

In editor-integrated workflows, it’s easy to jump between multiple Pythons without noticing. Packages installed into one interpreter won’t appear in another, which leads to confusing import errors even though the CLI works. Aligning your editor, terminal, and tooling to the same environment saves time and avoids the drift that causes these problems.

Takeaways

Decide whether you’re using a uv project or the uv global tool and stick to that choice for both installation and execution. For projects, prefer uv init and uv add manim, then run code through the project interpreter, activate .venv, or use uv run. In VSCode, explicitly select the same interpreter. If you opted for a global tool, follow the docs to configure your editor so import manim resolves properly. Once everything points to the same Python, the No module named 'manim' error disappears.