Manim 安装报错全解：latex / ffmpeg / dvisvgm / pycairo 等 12 个高频报错
A field guide to the twelve errors that stop most beginners, indexed by the exact message you see. The biggest cluster is LaTeX-related: "latex not found", non-zero exit from the latex command, and missing dvisvgm all mean your TeX distribution is absent, too minimal, or not on PATH — install MiKTeX/TeX Live with dvisvgm and let MiKTeX auto-install packages. Second cluster is toolchain: ffmpeg not found, pycairo/ManimPango build failures on Linux (install the -dev packages before pip), and wheels missing on too-new Python versions. Third cluster is environment: Chinese or spaced paths on Windows, wrong interpreter/venv, and OpenGL renderer glitches. Each entry gives the cause, the fix command per OS, and how to verify.
按报错原文找答案
以下报错全部来自真实提问（GitHub Issues、知乎、Stack Overflow 高频），按出现频率排序。直接复制你屏幕上的报错关键词来搜索本页。
1. LaTeX 报错：Writing to moviepy / latex not found
报错原文：FileNotFoundError: [Errno 2] No such file or directory: 'latex' 或渲染 MathTex 时 An error occurred whilst rendering withTex。
原因：没装 LaTeX 发行版，或装了但不在 PATH。Manim 用 latex 把公式编译成 dvi，再用 dvisvgm 转 SVG，两个工具缺一不可。
修复：
- Windows：装 MiKTeX（勾选添加 PATH）
- macOS：
brew install --cask mactex-no-gui - Ubuntu/Debian：
sudo apt install texlive texlive-latex-extra texlive-fonts-recommended
验证：latex --version && dvisvgm -v 都有输出。
2. latex 命令返回非零退出码
报错原文：Command '['latex', '-interact=nonstopmode', ...]' returned non-zero exit status 1
原因：LaTeX 装了但缺宏包（最常见缺 standalone、dvisvgm、preview），或公式语法本身有错。
修复：MiKTeX 首次编译会弹窗问"是否安装缺失宏包"，选 Always；Linux 装 texlive-latex-extra；仍失败就把报错里的公式拿出来先在本地 latex 编译排查语法。
3. dvisvgm: command not found
原因：dvisvgm 不在 PATH，或版本过老（小于 2.4 对某些宏包支持差）。
修复：MiKTeX 用户在 MiKTeX Console 里安装 dvisvgm 包；macOS 用 MacTeX 自带的即可；Linux sudo apt install texlive-extra-utils。
4. ffmpeg not found
报错原文：You are trying to use ffmpeg but it is not installed / FileNotFoundError: 'ffmpeg'
修复：Windows winget install ffmpeg；macOS brew install ffmpeg；Linux sudo apt install ffmpeg。装完重开终端再跑。
5. pycairo 编译失败
报错原文：ERROR: Failed building wheel for pycairo，日志里 fatal error: cairo.h: No such file or directory
原因：Linux 缺 cairo 开发头文件；或 pip 没有对应平台的预编译 wheel（常见于过新的 Python 版本）。
修复：
- Debian/Ubuntu：
sudo apt install libcairo2-dev pkg-config python3-dev后重试 - Fedora：
sudo dnf install cairo-devel - 仍失败：把 Python 降到 3.11/3.12 建 venv 重装
6. ManimPango 编译失败
原因：缺 pango 开发库。
修复：sudo apt install libpango1.0-dev（Debian/Ubuntu）后重新 pip install manim。
7. Windows 路径含中文或空格导致渲染失败
症状：项目放在 桌面、我的文档 或含空格目录下，报各种奇怪的编码错误或 moviepy 崩溃。
修复：把项目移到纯英文无空格路径，如 D:\manim-projects\。这是 Windows 平台独有的坑，LaTeX 子进程对非 ASCII 路径支持很差。
8. ModuleNotFoundError: No module named 'manim'
原因：装到了另一个 Python 环境（多版本共存 / venv 没激活 / 用了 conda 的 python 但 pip 是系统的）。
修复：统一用 python -m pip install manim 和 python -m manim ... 保证解释器一致；检查 where python 与 where pip 是否同一环境。
9. No scenes found / 场景类没有被渲染
原因：命令行没写场景名且文件里有多个 Scene；或类名拼错、没继承 Scene。
修复：显式指定 manim -pql demo.py S01Hello；渲染全部场景加 -a。
10. OpenGL 渲染器黑屏或崩溃
原因：--renderer=opengl 依赖显卡驱动，远程桌面/虚拟机/老驱动容易黑屏。
修复：默认 cairo 渲染器足够日常使用；需要 OpenGL 实时预览时更新显卡驱动，避免在远程桌面会话里用。
11. 中文公式渲染报错 / 中文显示为方块
原因：MathTex 里的中文需要 ctex 宏包支持；Text 中文乱码是系统缺少对应字体。
修复：见《Manim 中文渲染与 LaTeX 配置》，包含 TexTemplate 配 ctex 的完整代码。
12. Python 3.13+ 装不上依赖
原因：pycairo/manimpango 等二进制依赖对新 Python 版本发 wheel 滞后几个月。
修复：用 Python 3.11 或 3.12 建环境（py -3.12 -m venv env），这是 2026 年最稳的组合。
还是解决不了？
把完整报错栈 + manim --version 输出 + 操作系统发到我们的交流群（见合作分享页），或先跑一遍标准安装流程排除环境问题。