Skip to content

D2 Rendering Backends

c4.renderers.d2.renderer.D2Renderer

A renderer for converting a Diagram object into D2 syntax.

__init__ 

__init__(
    render_options: D2RenderOptions | None = None,
    backend: BaseD2Backend | None = None,
    extension_validation_mode: ExtensionValidationModeType = IGNORE_FOREIGN,
) -> None

Parameters:

Name Type Description Default
render_options D2RenderOptions | None

Render options that control D2 text rendering.

 None
backend BaseD2Backend | None

Optional D2 backend used for image rendering.

 None
extension_validation_mode ExtensionValidationModeType

Policy for foreign backend extensions.

 IGNORE_FOREIGN

validate 

validate(diagram: TDiagram) -> None

Validate D2-specific rendering constraints.

render 

render(diagram: TDiagram) -> str

Render the given Diagram into D2 format.

Parameters:

Name Type Description Default
diagram TDiagram

The diagram to render.

 required

Returns:

Type Description
str

A D2-formatted string representing the diagram.

render_bytes 

render_bytes(
    diagram: TDiagram, *, format: DiagramFormat
) -> bytes

Render a Diagram and return raw bytes.

This method first converts the Diagram into D2 source text and then delegates the actual rendering to the configured D2 backend.

Parameters:

Name Type Description Default
diagram TDiagram

The diagram instance to render.

 required
format DiagramFormat

Output format of the rendered diagram.

 required

Returns:

Type Description
bytes

The rendered diagram content as raw bytes.

Raises:

Type Description
D2BackendConfigurationError

If no D2 backend is configured for this renderer.
D2Error

If the underlying D2 backend fails to render the diagram.

render_file 

render_file(
    diagram: TDiagram,
    output_path: str | Path,
    *,
    format: DiagramFormat,
    overwrite: bool = True,
) -> Path

Render a Diagram and write the result to a file.

This method first converts the Diagram into D2 source text and then delegates file generation to the configured D2 backend.

Parameters:

Name Type Description Default
diagram TDiagram

The diagram instance to render.

 required
output_path str | Path

Path where the rendered diagram should be written.

 required
format DiagramFormat

Output format of the rendered diagram.

 required
overwrite bool

Whether to overwrite the output file if it already exists.

 True

Returns:

Type Description
Path

Path to the written output file.

Raises:

Type Description
D2BackendConfigurationError

If no D2 backend is configured for this renderer.
FileExistsError

If the output file exists and overwrite is set to False.
D2Error

If the underlying D2 backend fails to render or write the diagram.

c4.renderers.d2.backends.BaseD2Backend

Generate D2 diagrams from plain text.

A generator takes D2 diagram source text and produces image bytes (or writes them to a file).

to_bytes abstractmethod 

to_bytes(
    diagram: str,
    *,
    format: DiagramFormat = PNG,
    render_options: D2RenderOptions | None = None,
) -> bytes

Generate a D2 diagram and return the generated image as bytes.

Parameters:

Name Type Description Default
diagram str

D2 diagram source text.

 required
format DiagramFormat

Output image format, such as 'svg', 'png', or 'pdf'.

 PNG
render_options D2RenderOptions | None

Optional D2 render options used by backends that support renderer-controlled export flags.

 None

Returns:

Type Description
bytes

Rendered image content as raw bytes.

Raises:

Type Description
D2RenderingError

If rendering fails.

to_file 

to_file(
    diagram: str,
    output_path: str | Path,
    *,
    format: DiagramFormat | None = PNG,
    overwrite: bool = True,
    render_options: D2RenderOptions | None = None,
) -> Path

Generate a D2 diagram and write the generated image to a file.

Parameters:

Name Type Description Default
diagram str

D2 diagram source text.

 required
output_path str | Path

Path where the rendered image should be written.

 required
format DiagramFormat | None

Output image format. If None, the format is inferred from output_path suffix.

 PNG
overwrite bool

Whether to overwrite the output file if it already exists.

 True
render_options D2RenderOptions | None

Optional D2 render options used by backends that support renderer-controlled export flags.

 None

Returns:

Type Description
Path

Path to the written output file.

c4.renderers.d2.backends.LocalD2Backend

Bases: BaseD2Backend

Generate D2 diagrams using the local D2 executable.

Env vars
  • D2_BIN: executable name/path (default: 'd2')

__init__ 

__init__(
    *,
    d2_bin: Maybe[str | None] = MISSING,
    timeout_seconds: Maybe[float] = MISSING,
    d2_args: Sequence[str] = (),
    layout: D2Layout | None = None,
    env: Mapping[str, str] | None = None,
) -> None