docling-project/docling · error · SystemExit

Plotting requires matplotlib. Install it in the environment

Error message

Plotting requires matplotlib. Install it in the environment first.

What it means

SystemExit raised by main() in perfs/plot_memory_metrics.py when 'import matplotlib.pyplot' fails with ImportError. matplotlib is an optional dependency used only for rendering the memory-over-time plot, so the script gives an actionable install message instead of a traceback.

Source

Thrown at perfs/plot_memory_metrics.py:120

            if event == "loaded":
                memory_loaded = payload.get("memory_loaded_mb")
                if isinstance(memory_loaded, dict):
                    total_pages.append(total_page_no)
                    _append_memory_values(loaded_metrics, memory_loaded)

    return total_pages, loaded_metrics


def main() -> None:
    args = parse_args()
    if not args.input_file.is_file():
        raise SystemExit(f"Input file does not exist: {args.input_file}")

    try:
        import matplotlib.pyplot as plt
    except ImportError as exc:
        raise SystemExit(
            "Plotting requires matplotlib. Install it in the environment first."
        ) from exc

    loaded_runs = []
    for label, metrics_file in _resolve_metrics_files(args.input_file):
        if not metrics_file.is_file():
            raise SystemExit(f"Metrics file does not exist: {metrics_file}")
        total_pages, loaded_metrics = load_points(metrics_file)
        if total_pages:
            loaded_runs.append((label, total_pages, loaded_metrics))

    if not loaded_runs:
        raise SystemExit(f"No plotable data found in {args.input_file}")

    fig, ax = plt.subplots(1, 1, figsize=(12, 6))

    for label, total_pages, loaded_metrics in loaded_runs:
        point_count = min(

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install matplotlib in the same environment: 'pip install matplotlib' (or 'uv pip install matplotlib').
Add matplotlib to the perf tooling's requirements/dev extras so benchmark environments always include it.
If you only need the numbers, skip plotting and read the .jsonl metrics directly instead.

Example fix

# before
$ uv run python perfs/plot_memory_metrics.py summary.json
# SystemExit: Plotting requires matplotlib. Install it in the environment first.

# after
$ uv pip install matplotlib
$ uv run python perfs/plot_memory_metrics.py summary.json

Defensive patterns

Strategy: try-catch

Validate before calling

try:
    import matplotlib.pyplot  # noqa: F401
except ImportError:
    raise SystemExit("Install matplotlib: pip install matplotlib")

Try / catch

try:
    import matplotlib.pyplot as plt
except ImportError:
    plt = None

if plt is None:
    # export the series as CSV/JSON instead of plotting
    ...

Prevention

Include matplotlib in the perf tooling requirements file.
Provision a plotting stage in CI with matplotlib preinstalled.
When plotting is optional, degrade to writing the data series instead of failing.

When it happens

Trigger: Running plot_memory_metrics.py in any environment where matplotlib is absent — e.g. the docling runtime venv, a slim container, or a linting/production image that intentionally excludes plotting libraries.

Common situations: Performance benchmarking environments provisioned with only the packages needed to run conversions; CI images that minimize size; Python environments where matplotlib was uninstalled or never added to requirements.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/6da59f43356d480e. Report an issue: GitHub.