How to Use Manim's YAML Configuration System (including custom_config.yml)

Manim merges three hierarchical levels of YAML configuration—base defaults from manimlib/default_config.yml, project-specific overrides from a custom_config.yml file in your working directory, and command-line arguments—to determine final runtime settings.

The 3b1b/manim library uses a flexible YAML configuration system that lets you customize rendering behavior without modifying source code. By leveraging custom_config.yml alongside the base default_config.yml, you can control everything from camera resolution to LaTeX templates across your projects.

Understanding Manim's Configuration Hierarchy

Manim's YAML configuration system operates on three distinct levels that are merged recursively at startup:

• Base defaults: manimlib/default_config.yml provides built-in defaults for directories, window settings, camera parameters, file writing options, and text rendering.

• Project-specific overrides: A custom_config.yml file placed in your working directory (or any parent folder) can redefine any subset of keys from the default file.

• CLI overrides: Command-line arguments such as --config_file <path> or individual flags take the highest precedence.

How Manim Loads and Merges YAML Files

The configuration initialization happens in initialize_manim_config() within manimlib/config.py (lines 23–30). This function executes the following sequence:

1. Loads built-in defaults via load_yaml("default_config.yml").

2. Attempts to load custom_config.yml from the current working directory using load_yaml("custom_config.yml") (line 37).

3. Merges the dictionaries recursively using merge_dicts_recursively, where values from custom_config.yml override defaults, and CLI arguments override both.

4. Stores the final merged dictionary in the module-level variable manim_config (line 399).

The load_yaml function (around line 336) safely reads YAML files and returns an empty dictionary if the file does not exist, ensuring that missing custom_config.yml files do not cause errors.

Default Configuration Structure

The manimlib/default_config.yml file organizes settings into logical sections:

• Directories (lines 11–34): Defines mirror_module_path, output, raster_images, vector_images, downloads, tex, and text subdirectories.

• Window (lines 41–49): Controls window position, monitor selection, and full-screen behavior.

• Camera (lines 52–56): Specifies resolution, background color, and frame rate.

• File writer (lines 57–64): Configures ffmpeg command, video codec, pixel format, and quality settings.

• Tex & Text (lines 82–92): Sets LaTeX template names, font configurations, and alignment options.

Creating a custom_config.yml File

To override defaults, create a custom_config.yml file in your project directory. You only need to specify the keys you want to change; unspecified keys inherit from default_config.yml.

Example custom_config.yml:

directories:
  subdirs:
    output: "my_videos"

camera:
  resolution: [1280, 720]
  background_color: "#000000"
  fps: 60

file_writer:
  video_codec: "libx265"
  pixel_format: "yuv420p10le"

Place this file in the folder where you run the manim command (or any parent folder), and Manim will automatically detect and merge it.

Accessing Configuration Values in Python Code

You can inspect and use the active configuration at runtime by importing the manim_config dictionary from manimlib.config:

from manimlib.config import manim_config

# Retrieve current camera resolution

width, height = manim_config["camera"]["resolution"]
print(f"Rendering at {width}×{height}")

# Check output directory setting

output_dir = manim_config["directories"]["subdirs"]["output"]
print(f"Videos saved to: {output_dir}")

The Scene class merges manim_config.camera with per-scene overrides during initialization (see Scene.__init__ lines 88–94).

Overriding Settings for Individual Scenes

For temporary changes that apply only to a specific scene, use the temp_config_change context manager available in the Scene class. This ensures settings revert automatically after the scene completes.

Example:

from manimlib import *

class HighResScene(Scene):
    def construct(self):
        # Temporarily switch to 4K resolution for this scene only

        with self.temp_config_change(
            {"camera": {"resolution": (3840, 2160)}}
        ):
            circle = Circle()
            self.add(circle)
            self.wait()

The temp_config_change method is defined at line 714 in manimlib/scene/scene.py.

Custom LaTeX Templates via YAML

Manim also supports custom LaTeX templates through manimlib/tex_templates.yml. You can reference these templates in your custom_config.yml:

tex:
  template: "my_template"

To create a new template, add an entry to tex_templates.yml (see lines 1–3 for the structure). The template system is loaded via yaml.safe_load in manimlib/utils/tex_file_writing.py (line 23).

Summary

• Manim uses a three-tier YAML configuration system: base defaults (manimlib/default_config.yml), project overrides (custom_config.yml), and CLI arguments.
• The initialize_manim_config() function in manimlib/config.py merges these hierarchically using merge_dicts_recursively.
• Place custom_config.yml in your working directory to override specific keys without modifying source code.
• Access runtime configuration via manim_config imported from manimlib.config.
• Use temp_config_change in scenes for temporary, scope-limited configuration overrides.

Frequently Asked Questions

What is the order of precedence for Manim configuration files?

Manim applies configuration in the following order of increasing priority: first, the base defaults from manimlib/default_config.yml; second, any custom_config.yml found in the working directory or parent folders; and third, command-line arguments passed via flags or --config_file. Values from higher levels override those from lower levels.

Where should I place my custom_config.yml file?

Place the custom_config.yml file in the directory from which you run the manim command, or in any parent folder of that directory. Manim searches for this file automatically during initialization in manimlib/config.py and merges it with the default configuration.

Can I use command-line arguments to override YAML settings?

Yes, command-line arguments take the highest precedence in Manim's configuration hierarchy. You can specify individual flags like -p or --quality, or provide an alternative configuration file using --config_file <path> to override settings defined in custom_config.yml or the defaults.

How do I temporarily change settings for a single scene?

Use the temp_config_change context manager available in the Scene class. This method accepts a dictionary of configuration overrides that apply only within the with block, ensuring that settings revert automatically after the scene completes. This is defined at line 714 in manimlib/scene/scene.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}