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

> Master Manim's YAML configuration system. Learn how to customize settings using default configuration, custom_config.yml and command-line arguments for precise control over your animations.

- Repository: [Grant Sanderson/manim](https://github.com/3b1b/manim)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Manim merges three hierarchical levels of YAML configuration—base defaults from [`manimlib/default_config.yml`](https://github.com/3b1b/manim/blob/main/manimlib/default_config.yml), project-specific overrides from a [`custom_config.yml`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/custom_config.yml) alongside the base [`default_config.yml`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/custom_config.yml) files do not cause errors.

## Default Configuration Structure

The [`manimlib/default_config.yml`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/default_config.yml).

Example [`custom_config.yml`](https://github.com/3b1b/manim/blob/main/custom_config.yml):

```yaml
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`:

```python
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:

```python
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`](https://github.com/3b1b/manim/blob/main/manimlib/scene/scene.py).

## Custom LaTeX Templates via YAML

Manim also supports custom LaTeX templates through [`manimlib/tex_templates.yml`](https://github.com/3b1b/manim/blob/main/manimlib/tex_templates.yml). You can reference these templates in your [`custom_config.yml`](https://github.com/3b1b/manim/blob/main/custom_config.yml):

```yaml
tex:
  template: "my_template"

```

To create a new template, add an entry to [`tex_templates.yml`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/manimlib/utils/tex_file_writing.py) (line 23).

## Summary

- Manim uses a three-tier YAML configuration system: base defaults ([`manimlib/default_config.yml`](https://github.com/3b1b/manim/blob/main/manimlib/default_config.yml)), project overrides ([`custom_config.yml`](https://github.com/3b1b/manim/blob/main/custom_config.yml)), and CLI arguments.
- The `initialize_manim_config()` function in [`manimlib/config.py`](https://github.com/3b1b/manim/blob/main/manimlib/config.py) merges these hierarchically using `merge_dicts_recursively`.
- Place [`custom_config.yml`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/manimlib/default_config.yml); second, any [`custom_config.yml`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/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`](https://github.com/3b1b/manim/blob/main/manimlib/scene/scene.py).