上一篇把 Python 环境准备好了,这篇开始装 Manim 本体。全程按 2026 年 11 月的官方文档来:先分清版本,再选安装路线,最后用 checkhealth 体检并渲染出第一段动画。

前提:Python ≥ 3.11。还没装好请先读 第一篇:把 Python 环境装对。本文所有命令默认在项目根目录下执行。

一、先分清你装的是哪个 Manim

图 1:三个 Manim 版本的区别

Manim 最初是 3Blue1Brown 作者 Grant Sanderson 的个人项目,后来社区分叉维护,才有了今天三个同名但互不兼容的东西。判断方法很简单:看代码第一行的 import。

版本 PyPI 包名 典型导入 用途
ManimCE manim from manim import * 社区版,本文与官方文档采用
ManimGL manimgl import manimlib 3b1b 本人使用的实验版
ManimCairo manimlib from manimlib.imports import * 仅用于复现 2019 年前的旧视频

官方明确提醒:网上大量视频安装教程已经严重过时,因为视频没法随版本更新而修改。装不上时优先对照官方文档,别反复重看同一段视频。

本文只装 ManimCE,也就是 pip install manim 装到的那个。两个版本不要混装,否则 manim 命令可能指向错误的可执行文件。

图 2:Manim 0.22.x 的依赖分层与可选部分

二、选一条安装路线

路线 适合谁 一句话
A. uv 绝大多数人 官方强烈推荐,三条命令搞定,环境自动隔离
B. pip + venv 已经熟悉 Python 沿用第一篇装的 Python,手动管理虚拟环境
C. Conda 已有 Anaconda / Miniconda 依赖(除 LaTeX)全由 conda 打包,跨平台步骤一致
D. Docker 不想碰本机环境 用官方镜像 manimcommunity/manim
E. 在线体验 只想先看看 https://try.manim.community,零安装

下面把 A、B、C 三条都写全,选一条走完即可,不要三条混着来。


三、路线 A:uv(官方推荐)

Step 0:确认 uv 可用

第一篇已经装过就跳过。没有的话,Windows PowerShell 执行:

1
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux:

1
curl -LsSf https://astral.sh/uv/install.sh | sh

重开终端,uv --version 能返回版本号即可。

Step 1:准备 Python

uv 可以自己下载并管理 Python,不必依赖系统里装的那一份:

1
uv python install

想指定版本,在初始化项目时传参即可:

1
uv init --python 3.14 manimations

Step 2:建项目并装 Manim

1
2
3
uv init manimations
cd manimations
uv add manim

manimations 只是项目目录名,换成任何你喜欢的名字都行。三条命令分别做了:创建项目骨架、进入目录、把 Manim 作为依赖装进这个项目的本地环境。

执行完目录里会多出几样东西:

1
2
3
4
5
6
manimations/
├─ .venv/ 本地虚拟环境,Manim 装在这里
├─ pyproject.toml 项目声明,记录依赖
├─ uv.lock 精确锁定的版本
├─ main.py 示例入口文件
└─ .python-version 项目使用的 Python 版本

因为 Manim 装在项目的 .venv 里,没有全局激活,直接敲 manim 会提示命令找不到。正确写法是给每条命令加前缀:uv run manim ...。也可以先按 uv venv 打印的提示激活环境,之后就能省略前缀。

截图位 B:终端里 uv add manim 成功后的输出,以及 uv run manim checkhealth 的全绿结果。建议保存为 uploads/allimg/2026/0198/uv-add-manim.png 后插入本节。

Windows 专属:提示需要 Microsoft Visual C++

如果 uv add manim 报缺少 C++ 编译器,去装 Microsoft C++ Build Tools,在 Visual Studio Installer 里勾选 Desktop development with C++。装完重开终端,再跑一次 uv add manim。

多数 Windows 机器有预编译包,不会走到这一步;遇到了照做即可,不必卸载重装。


四、路线 B:传统 pip + venv

沿用第一篇装好的 Python,手动建虚拟环境。Windows:

1
2
3
4
5
python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install manim
manim --version

macOS / Linux:

1
2
3
4
5
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install manim
manim --version

国内网络慢可以在 pip install manim 后加 -i https://pypi.tuna.tsinghua.edu.cn/simple。

这条路线的特点是:只要终端提示符前有 (.venv),manim 就能直接调用;关掉终端后下次要重新激活。如果不想激活,等价写法是 python -m manim --version。

五、路线 C:Conda

Conda 的好处是 pycairo 之类的系统级依赖由它一并打包,Windows、Linux、Intel Mac、Apple Silicon 步骤完全一致。

1
2
3
conda create -n my-manim-environment
conda activate my-manim-environment
conda install -c conda-forge manim

用 pixi 的话更短:

1
2
pixi init
pixi add manim

官方文档说明:除 LaTeX 外,所有依赖都由 conda 处理,无需再手动补系统库。如果 Anaconda 环境报 ImportError 并提到某个 symbol 找不到,是它自带的 cairo 与 Manim 需要的 pycairo 不兼容,用下面这条修:

1
conda install -c conda-forge pycairo

六、系统依赖,以及一个「老教程陷阱」

先说 ffmpeg

几乎每一篇 2023 年前后的 Manim 教程,都会让你先装 ffmpeg、再苦哈哈配 PATH。按当前官方文档和 pyproject.toml 的依赖清单,这一步现在不需要了:Manim 0.19 之后视频编码改由 av(PyAV)在 Python 包内部完成,0.22.1 的依赖里明确写着 av>=15.0,官方安装页也完全没提手动安装 ffmpeg。

如果你用的是很旧的版本,或者 checkhealth 明确报告 ffmpeg 不可用,再补装不迟:

1
2
# Windows
winget install ffmpeg
1
2
3
4
5
# macOS
brew install ffmpeg

# Debian / Ubuntu
sudo apt install ffmpeg

各平台真正还要装的东西

Windows:通常什么都没有。只有上面提到的 C++ Build Tools 可能需要。

macOS:pycairo 需要系统工具 cairo 和 pkg-config,先用 brew --version 确认 Homebrew 在不在,然后:

1
brew install cairo pkg-config

Linux:ManimPango 和 pycairo 可能需要从源码构建,要补齐 C 编译器、Python 开发头文件、pkg-config、Pango 与 Cairo 的开发头文件。

1
2
3
4
5
6
7
8
9
# Debian / Ubuntu(apt)
sudo apt update
sudo apt install build-essential python3-dev libcairo2-dev libpango1.0-dev

# Fedora(dnf)
sudo dnf install python3-devel pkg-config cairo-devel pango-devel

# Arch(pacman)
sudo pacman -Syu base-devel cairo pango

七、LaTeX:可选,用到公式再装

Manim 用 Text 渲染普通文字时不碰 LaTeX;只有 Tex、MathTex 这类排版数学公式的对象才需要。官方把 LaTeX 明确列为可选依赖,所以第一次安装完全可以先跳过,等真的要写公式了再回来补。

系统 推荐发行版
Windows MiKTeX
macOS MacTeX
Linux TeX Live:sudo apt install texlive-full;Fedora 用 sudo dnf install texlive-scheme-full

Windows 装 MiKTeX 后,第一次渲染 MathTex 可能弹窗询问是否自动安装缺失的宏包,勾「总是安装」即可,别手动取消。

如果用了 TinyTeX 之类的精简发行版,官方给出的最小宏包清单如下,缺哪个补哪个:

1
2
3
4
amsmath babel-english cbfonts-fd cm-super count1to ctex doublestroke dvisvgm
everysel fontspec frcursive fundus-calligra gnu-freefont jknapltx latex-bin
mathastext microtype multitoc physics preview prelim2e ragged2e relsize rsfs
setspace standalone tipa wasy wasysym xcolor xetex xkeyval

完整发行版动辄几个 GB,但它能一次性避开 preview.sty not found、amsmath not found 这类最常见的公式报错。磁盘够的话建议直接装全。


八、验收:checkhealth

不管走哪条路线,装完先体检。uv 路线:

1
uv run manim checkhealth

pip / conda 路线(环境已激活):

1
manim checkhealth

这个子命令会逐项检查 manim 是否在 PATH 上、可执行文件是否属于当前这个库、以及 LaTeX 等外部依赖是否可用,缺什么会直接给出对应的修复建议。逐条读它的输出,比自己猜快得多。

再确认版本归属:

1
uv run manim --version

输出第一行应当是 Manim Community v0.22.1(版本号随发布变化)。如果这一行没有 Manim Community 字样,说明你装的其实是 ManimGL,回去检查包名和 pip list。

1
2
# Windows 也可这样确认包装在哪套环境里
python -m pip list | findstr manim

截图位 C:checkhealth 的完整输出。读者最想看的其实就是「全绿」长什么样。

九、渲染第一个动画

在项目根目录新建 scene.py,贴入下面两段场景。第一段画一个粉色圆,第二段是 Manim 经典的「正方形变圆」:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
from manim import *


class CreateCircle(Scene):
def construct(self):
circle = Circle()
circle.set_fill(PINK, opacity=0.5)
self.play(Create(circle))


class SquareToCircle(Scene):
def construct(self):
circle = Circle()
circle.set_fill(PINK, opacity=0.5)
square = Square()
square.rotate(PI / 4)

self.play(Create(square))
self.play(Transform(square, circle))
self.play(FadeOut(square))

uv 路线渲染(注意前缀):

1
2
uv run manim -pql scene.py CreateCircle
uv run manim -pql scene.py SquareToCircle

pip / conda 路线,环境已激活时去掉前缀:

1
manim -pql scene.py SquareToCircle

-p 表示渲染完自动播放,-ql 表示低画质快速预览。常用参数:

参数 含义
-p 渲染完成后自动打开播放器
-ql 低画质 854×480、15fps,开发期首选
-qm / -qh 中画质 720p30 / 高画质 1080p60
-qp / -qk 2K / 4K,均 60fps
-s 只保存最后一帧 PNG,最快的检查方式
-o 指定输出文件名
--media_dir 指定输出根目录

看到粉色正方形平滑变成圆再淡出,整条链路就通了。

图 3:从脚本到视频的流程与输出目录结构

成片不在根目录,按「模块名 / 画质 / 场景名」三层往下找:

1
2
3
4
5
6
7
8
9
10
project/
├─ scene.py
└─ media/
├─ videos/
│ └─ scene/
│ └─ 480p15/
│ ├─ SquareToCircle.mp4
│ └─ partial_movie_files/
├─ texts/
└─ Tex/

partial_movie_files、texts、Tex 都是 Manim 自己维护的中间文件,不用手工清理。换成 -qh 渲染,会并排多出一个 1080p60 目录。

截图位 D:播放器里「正方形变圆」的任意一帧,或者 media/videos/scene/480p15/ 的文件管理器截图。

官方还提供一个项目脚手架,想按标准结构起步可以用:

1
uv run manim init project my-project --default

十、常见报错对照表

症状 原因 解法
'manim' 不是内部或外部命令 没激活虚拟环境,或 uv 项目环境未激活 用 uv run manim ...,或 python -m manim ...
输入 python 弹出 Microsoft Store 应用执行别名抢占 设置里关闭 python / python3 别名
uv add manim 提示需要 Microsoft Visual C++ 缺 C++ 生成工具 装 Build Tools 勾 Desktop development with C++,重开终端重试
manimpango 编译失败、cmanimpango.c 找不到 无对应架构的预编译包,转为本地构建 先 pip install Cython 重试;Linux 补齐第六节的开发头文件
提示 Python 版本不满足 解释器低于 3.11 uv python install 3.14 或 uv init --python 3.14 ...
MathTex 报 preview.sty / amsmath 缺失 LaTeX 发行版太精简 装完整 TeX 发行版,或按第七节清单补宏包
Anaconda 环境 ImportError 提到 symbol not found conda 自带 cairo 与 pycairo 不兼容 conda install -c conda-forge pycairo
渲染成功却找不到 mp4 没在项目根目录执行,或找错画质目录 到 media/videos/<模块名>/<画质>/ 下找
--version 首行没有 Manim Community 装成了 ManimGL 卸载 manimgl,确认装的是 manim

十一、进阶玩法(可以先跳过)

项目散落在很多目录、不想每个都建一遍环境,可以把 Manim 装成全局工具:

1
2
uv tool install manim
uv tool dir

第二条给出工具环境的路径,把这个虚拟环境设为 IDE 的解释器,import manim 才能正确补全。

其他几个官方给出的用法:

1
2
3
4
5
6
7
8
# 指定 Python 版本初始化
uv init --python 3.12 manimations

# 启用 Typst 渲染(依赖自带编译器,无需系统安装)
uv add "manim[typst]"

# 安装最新开发版(可能不稳定)
uv add git+https://github.com/ManimCommunity/manim.git@main

VS Code 有个叫 Manim Sideview 的扩展,能边写边预览动画,但官方特别说明它不由社区维护,出问题找扩展作者。

小结

到这一步你应该已经有一条能复用的命令了:uv run manim -pql <文件> <场景名>。

正式开始写 Scene、Mobject、Animation 之前,中文环境还有一件绕不开的小事:让中文和数学公式正常显示,见 第三篇:中文、字体与公式排版。那是安装部分的最后一块补遗,之后就进入真正做动画的内容。

返回第一篇:把 Python 环境装对

参考与配图

本站为非官方个人博客,与 Manim Community 及 3Blue1Brown 无隶属关系。遇到安装问题请以官方文档为准。