[opensourcedex]

d2 is a free, open source frameworks & platforms project written in Go and released under MPL-2.0. It has 25,506 GitHub stars, 752 forks and 530 open issues, and was last pushed 5 days ago. On this registry it ranks #22 of 72 tracked projects in Frameworks & Platforms, with 5 head-to-head comparisons available.

What is d2?

D2 is a modern diagram scripting language, written in Go and released under the MPL-2.0 licence, that turns plain-text .d2 files into rendered diagrams such as SVGs, aimed at developers and teams who want their architecture and system diagrams kept as reviewable source rather than as opaque image files.

What it is

D2 is an open-source diagram scripting language and command-line toolchain, developed in the d2lang GitHub organisation and written in Go. It sits in the text-to-diagram ecosystem: an author describes a system declaratively in a .d2 source file, and the D2 CLI compiles that description into a rendered diagram, with SVG output shown in the project quickstart. The language covers named shapes including cylinder, hexagon, person, page and stored_data, plus styling modifiers such as style.multiple and style.stroke-dash. A vars block carries d2-config settings that select the layout engine, demonstrated with elk, and the theme, including terminal-style code themes set by theme-id.

The concrete problem it addresses is that diagrams created in graphical editors are usually exported as images and committed as binary artefacts, which cannot be diffed, reviewed or regenerated reliably. D2 replaces that exported image file as the unit of storage: the .d2 source becomes the checked-in artefact, so a change to an architecture diagram appears as a readable text diff in a pull request, and the rendered output is reproduced by re-running a command instead of being redrawn by hand.

Key capabilities

  • Text-to-diagram compilation from the command line: running d2 --watch in.d2 out.svg builds an SVG from a .d2 source file and opens a browser window that live-reloads when the source changes.
  • Selectable layout engines through the d2-config layout-engine setting, with elk used in the documented example.
  • Theming and font support, including numbered theme identifiers for code-styled output.
  • A documented range of export file types, with SVG as the illustrated default path in the quickstart.
  • A shape vocabulary covering cylinder, hexagon, person, page and stored_data, combined with style modifiers such as style.multiple and style.stroke-dash.
  • Extensibility through official plugins and community plugins, alongside a dedicated language tooling section.
  • Use as a library rather than only as a CLI, with the npm package @d2lang/d2 published for JavaScript consumers and a Go install path for others.

Who uses it and how

  • Teams documenting software architecture, which the project's own topic list calls out explicitly, keeping diagram sources beside the systems they describe.
  • Open-source maintainers: the README maintains a list of notable open-source projects documenting with D2, so it is already used inside other projects' documentation trees.
  • Go developers, who can install it directly from source with go install github.com/d2lang/d2@latest and embed it in their own tooling.
  • JavaScript and TypeScript developers, who can consume the same engine through the @d2lang/d2 npm package.
  • Evaluators and newcomers, who can try the language without installing anything through the hosted playground at play.d2lang.com, or ask questions in the project's Discord server.

Getting started

The documented quickstart installs the CLI with the shell script at d2lang.com, run as curl -fsSL https://d2lang.com/install.sh | sh -s --, which also supports a --dry-run flag and an --uninstall flag. Alternatively, go install github.com/d2lang/d2@latest installs from source, and npm users can pull @d2lang/d2; a cheat sheet PDF and the docs site at d2lang.com accompany the install guide in docs/INSTALL.md.

How it compares

The facts provided do not list any paid or commercial products that D2 replaces, and they name no competing diagram tool by name; the README only points to a separate comparisons site at text-to-diagram.com without listing alternatives in the text supplied here. On the evidence available, D2 stands alone in this registry.

When to use it — and when not

D2 is a self-contained CLI and library rather than a service, so adopting it involves installing a binary, not operating a database, object store or mail server; the only hosted component mentioned is the optional playground. It is a poor fit for anyone who needs a diagram tool without a local toolchain at all, or who depends on a graphical canvas as the primary editing surface. Prospective adopters should also weigh the MPL-2.0 licence, which is file-level copyleft rather than permissive, and the fact that the repository carries roughly 530 open issues and that the README text available here is an excerpt pointing to the website and docs directory for the full picture.

project readme (upstream, from github) — read inline

A modern diagram scripting language that turns text to diagrams.

Docs | Cheat sheet | Comparisons | Playground

ci weekly race tests release changelog npm version discord license

https://user-images.githubusercontent.com/3120367/206125010-bd1fea8e-248a-43e7-8f85-0bbfca0c6e2a.mp4

Table of Contents

What does D2 look like?

vars: {
  d2-config: {
    layout-engine: elk
    # Terminal theme code
    theme-id: 300
  }
}
network: {
  cell tower: {
    satellites: {
      shape: stored_data
      style.multiple: true
    }

    transmitter

    satellites -> transmitter: send
    satellites -> transmitter: send
    satellites -> transmitter: send
  }

  online portal: {
    ui: {shape: hexagon}
  }

  data processor: {
    storage: {
      shape: cylinder
      style.multiple: true
    }
  }

  cell tower.transmitter -> data processor.storage: phone logs
}

user: {
  shape: person
  width: 130
}

user -> network.cell tower: make call
user -> network.online portal.ui: access {
  style.stroke-dash: 3
}

api server -> network.online portal.ui: display
api server -> logs: persist
logs: {shape: page; style.multiple: true}

network.data processor -> api server

Open in playground

For more examples, see ./docs/examples.

Quickstart

The most convenient way to use D2 is to just run it as a CLI executable to produce SVGs from .d2 files.

# First, install D2
curl -fsSL https://d2lang.com/install.sh | sh -s --

echo 'x -> y -> z' > in.d2
d2 --watch in.d2 out.svg

A browser window will open with out.svg and live-reload on changes to in.d2.

Install

The easiest way to install is with our install script:

curl -fsSL https://d2lang.com/install.sh | sh -s --

You can run the install script with --dry-run to see the commands that will be used to install without executing them.

Or if you have Go installed you can install from source though you won't get the manpage:

go install github.com/d2lang/d2@latest

You can also install a release from source which will include manpages. See ./docs/INSTALL.md#source-release.

To uninstall with the install script:

curl -fsSL https://d2lang.com/install.sh | sh -s -- --uninstall

For detailed installation docs, see ./docs/INSTALL.md. We demonstrate alternative methods and examples for each OS.

As well, the functioning of the install script is described in detail to alleviate any concern of its use. We recommend using your OS's package manager directly instead for improved security but the install script is by no means insecure.

D2 as a library

In addition to being a runnable CLI tool, D2 can also be used to produce diagrams from Go programs.

For examples, see ./docs/examples/lib.

Themes

D2 includes a variety of official themes to style your diagrams beautifully right out of the box. See ./d2themes to browse the available themes and make or contribute your own creation.

Fonts

D2 ships with "Source Sans Pro" as the font in renders. If you wish to use a different one, please see ./d2renderers/d2fonts.

Export file types

D2 supports SVG, PNG, GIF, PDF, and PPTX exports.

Language tooling

D2 is designed with language tooling in mind. D2's parser can parse multiple errors from a broken program, has an autoformatter, syntax highlighting, and we have plans for LSP's and more. Good language tooling is necessary for creating and maintaining large diagrams.

The extensions for VSCode and Vim can be found in the Related section.

Layout engines

D2 bundles three layout engines. Select one with --layout=dagre, --layout=elk, or --layout=tala. You can also set D2_LAYOUT or vars.d2-config.layout-engine in D2 source. Run d2 layout to list the engines or d2 layout for their configuration options.

  • Dagro (default, bundled): A native Go port of the Dagre directed graph layout engine that produces layered/hierarchical layouts. Based on Graphviz's DOT algorithm.
  • elk-go (bundled): A native Go port of the ELK directed graph layout engine, particularly suited for node-link diagrams with an inherent direction and ports.
  • TALA (bundled, opt-in): Native layout and edge-routing engine designed specifically for software architecture diagrams. Select it with --layout=tala, D2_LAYOUT=tala, or a layout-engine: tala setting under vars.d2-config in D2 source.

D2 also handles specialized layouts such as sequence diagrams and grids. Go applications can use the layout packages directly or provide layout and routing functions through d2lib.

Sketch-mode rendering uses rough-go, a native Go compatibility port of the Rough.js 4.6.6 rendering surface used by D2.

LaTeX labels use mathjax-go, a native Go port of the MathJax 3.2.2 TeX-to-SVG pipeline.

Comparison

For a comparison against other popular text-to-diagram tools, see https://text-to-diagram.com.

Contributing

Contributions are welcome! See ./docs/CONTRIBUTING.md.

License

Open sourced under the Mozilla Public License 2.0. See ./LICENSE.txt.

Related

We are constantly working on new plugins, integrations, extensions. Contributions are welcome in any official or community plugins. If you have somewhere in your workflow that you want to use D2, feel free to open a discussion. We have limited bandwidth and usually choose the most high-demand ones to work on. If you make something cool with D2 yourself, let us know and we'll be happy to include it here!

Official plugins

Community plugins

Misc

FAQ

  • Does D2 collect telemetry?
    • No, D2 does not use an internet connection after installation, except to check for version updates from Github periodically.
  • Does D2 need a browser to run?
    • No, D2 can run entirely server-side.
  • What's coming in the next release?
  • I have a question or need help.
    • The best way to get help is to ask on D2 Discord
  • I have a feature request, proposal, or bug report.
    • Please open up a Github Issue.
  • I have a private inquiry.

Notable open-source projects documenting with D2

Do you have or see an open-source project with .d2 files? Please submit a PR adding to this selected list of featured projects using D2.

Frequently asked questions

Is d2 free to use?

d2 is open source under the MPL-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does d2 do?

D2 is a modern diagram scripting language that turns text to diagrams.

What is d2 written in?

d2 is primarily written in Go. Its source is publicly available at https://github.com/d2lang/d2, and it has 25,506 GitHub stars.