Getting started with D2

Start in two minutes

You picked the CLI in watch mode, which is the most comfortable loop: you save the file, the browser tab refreshes with the new render.

1. Install

   The install script picks the best method for your machine (it uses your package manager if it can). Run it with --dry-run first to see what it will do.

   $ curl -fsSL https://d2lang.com/install.sh | sh -s -- --dry-run
   $ curl -fsSL https://d2lang.com/install.sh | sh -s --
   $ d2 --version

   Alternatives: go install github.com/d2lang/d2@latest, or a binary from GitHub releases. Since 0.9.0 the TALA engine and PNG/PDF/PPTX/GIF export are built in, so there is nothing else to install.

2. Create a file and start watching

   $ echo 'x -> y: hello world' > input.d2
   $ d2 -w input.d2 out.svg

   A browser tab opens and live-reloads on every save. Errors show up in that tab and in the terminal, with line numbers.

3. Get editor support

   Install the VS Code extension or the Vim plugin. Syntax highlighting catches many errors as you type: if a word suddenly changes color, it probably hit a reserved symbol.

4. Tidy and export

   $ d2 fmt input.d2
   $ d2 input.d2 out.png
   $ D2_LAYOUT=elk d2 -w input.d2 out.svg

   fmt fixes indentation and shortens imports. The output format follows the file extension (svg, png, pdf, pptx, gif, or txt for ASCII art). The last line shows how to switch layout engine for a session.

The mental model

D2 has very little syntax because almost everything is the same idea: a key, optionally a label, optionally a map of fields in braces. Read these six ideas once and most of the language becomes predictable.

# Key on the left, label on the right
be: Backend
fe: Frontend

# Connections use KEYS, not labels
fe -> be: calls

# Declared once...
api: Payments API

# ...then extended anywhere later.
# Same key = same object, settings merge.
api.shape: hexagon
api.style.fill: "#FFF4D6"

api -> ledger

aws: AWS {
  vpc: VPC {
    app: App server
  }
}

# Dots form a path to a nested key
aws.vpc.app -> aws.s3: uploads

Syntax basics

Each card shows the source on the left and what D2 0.9.0 actually rendered on the right. Every snippet opens in the Playground so you can tinker.

# A bare key creates a rectangle
server

# key: label
db: PostgreSQL
db.shape: cylinder

# Several shapes on one line
cache; jobs
jobs.shape: queue
cache.shape: stored_data

direction: right
client -> api: request
api <- worker: polls
api <-> cache
logs -- api

# Chaining: three connections
api -> db -> backup

direction: right
# A source arrowhead needs a source end: use <->
users <-> orders: places {
  source-arrowhead.shape: cf-one-required
  target-arrowhead.shape: cf-many
}

# Same pair twice = two connections
a -> b
a -> b

# Target one of them by index (0-based)
(a -> b)[1].style.stroke: red

cloud: AWS {
  lb: Load balancer
  api: API
  lb -> api
}

# Reach inside with a dot path
cloud.api -> cloud.db

office: Office {
  # _ means "my parent" (here: root)
  laptop -> _.cloud.lb: VPN
}

direction: right
api: {
  style: {
    fill: "#E8EEFF"
    stroke: "#0D32B2"
    stroke-width: 2
    border-radius: 8
    shadow: true
  }
}
workers.style.multiple: true

api -> workers: jobs {
  style.stroke-dash: 3
  style.animated: true
}

why: |md
  ### Why a queue?
  - absorbs traffic bursts
  - **retries** come for free
|

snippet: |go
  q.Publish(ctx, job)
|

hint: just floating text {shape: text}

why -> snippet

direction: right
# Free icon set: https://icons.d2lang.com
server: API server {
  icon: https://icons.d2lang.com/tech/022-server.svg
  tooltip: Runs on 3 nodes
  link: https://example.com/runbook
}

# shape: image shows the icon alone
github: {
  shape: image
  icon: https://icons.d2lang.com/dev/github.svg
}

server -> github: pulls code

title: |md
  # Checkout flow
| {near: top-center}

note: Draft, not final {
  shape: text
  near: bottom-right
}

cart -> payment -> receipt
payment.label.near: outside-top-center

classes: {
  service: {
    style.fill: "#E8EEFF"
    style.border-radius: 6
  }
  store: {
    shape: cylinder
    style.fill: "#FFF4D6"
  }
}

api.class: service
auth.class: service
db.class: store

api -> db
auth -> db

vars: {
  env: prod
  # Config that would otherwise be CLI flags
  d2-config: {
    layout-engine: elk
    pad: 20
  }
}

api: API (${env})
db: DB (${env})
api -> db

web -> api -> db
api -> cache
db.shape: cylinder
cache.shape: cylinder

# Every top-level shape
*.style.border-radius: 8

# Only shapes that are cylinders (filter with &)
*: {
  &shape: cylinder
  style.fill: "#FFF4D6"
}

# Every connection
(* -> *)[*].style.stroke-dash: 3

# Line comment
x -> y # trailing comment

"""
Block comment,
spanning lines
"""

# Quote labels that contain reserved symbols.
# Single quotes also stop ${...} substitution.
z: 'Price: $5 # not a comment'
# Hex colors MUST be quoted (# starts a comment)
z.style.fill: "#FFF4D6"

# Spread a whole file into this map
...@styles

# Import a file as the value of a key
team: @people

# Import just one object from a file
lead: @people.alice

team.bob -> api
api.class: svc

alice: Alice {shape: person}
bob: Bob {shape: person}

classes: {
  svc: {style.fill: "#E8EEFF"}
}

grid-rows: 3
grid-columns: 6
grid-gap: 16
rectangle: {shape: rectangle}
square: {shape: square}
page: {shape: page}
parallelogram: {shape: parallelogram}
document: {shape: document}
cylinder: {shape: cylinder}
queue: {shape: queue}
package: {shape: package}
step: {shape: step}
callout: {shape: callout}
stored_data: {shape: stored_data}
person: {shape: person}
c4-person: {shape: c4-person}
diamond: {shape: diamond}
oval: {shape: oval}
circle: {shape: circle}
hexagon: {shape: hexagon}
cloud: {shape: cloud}

Layout: how D2 places things

A layout engine computes every position from your description. You don't move boxes; you pull on four levers.

Lever 1: direction

Sets the flow of the whole diagram: down (default), up, right, left. With dagre and ELK it is global; only TALA lets you set it per container.

direction: right
plan -> build -> test -> ship
test -> build: fails

Lever 2: the layout engine

Three engines ship with D2. The same source below gives three quite different pictures:

users: Users {shape: person}
edge: Edge {
  cdn: CDN
  lb: Load balancer
}
core: Core services {
  api: API
  auth: Auth
  worker: Worker
}
data: Data {
  pg: Postgres {shape: cylinder}
  redis: Redis {shape: cylinder}
  bus: Event bus {shape: queue}
}
users -> edge.cdn -> edge.lb -> core.api
core.api -> core.auth
core.api -> data.pg
core.api -> data.redis
core.api -> data.bus -> core.worker
core.worker -> data.pg

Pick an engine with -l elk, D2_LAYOUT=elk, or in the file with vars: {d2-config: {layout-engine: elk}}. List engines and their options with d2 layout and d2 layout tala. For TALA's randomness, --tala-seeds controls the layout attempts.

Lever 3: grids

Setting grid-rows and/or grid-columns on the root or on a container switches it to a strict grid, which ignores the engine for placement. Whichever key comes first decides the fill order: rows first fills row by row. Set one key alone and cells stretch to fill. Space them with grid-gap, vertical-gap, horizontal-gap; grid-gap: 0 makes tables and stacks.

# grid-rows comes first, so cells fill row by row
grid-rows: 2
grid-columns: 3
grid-gap: 12

Web; Mobile; Partner API
Orders; Billing; Search

stack: Platform {
  grid-rows: 3
  grid-gap: 0
  apps: Applications {
    grid-columns: 3
    web; ios; android
  }
  runtime: Kubernetes
  infra: AWS
}

Lever 4: near, sizes and pinning

near with a corner constant takes a shape out of the flow (titles, legends, notes; see the near card). width and height fix a shape's size. With TALA only, near: other.shape keeps two shapes close and top + left pin one in place while the rest flows around it.

Recipes

Complete, working starting points for the diagrams you said you will write most. Copy one, rename the keys, and keep the structure.

vars: {
  d2-config: {
    layout-engine: elk
  }
  d2-legend: {
    svc: Internal service {
      style: {fill: "#E8EEFF"; stroke: "#0D32B2"}
    }
    ext: Third party {
      style: {fill: "#F2F4F7"; stroke: "#667085"; stroke-dash: 3}
    }
  }
}
direction: right

title: |md
  # Order platform, high level
| {near: top-center}

classes: {
  svc: {
    style: {fill: "#E8EEFF"; stroke: "#0D32B2"; border-radius: 6}
  }
  store: {
    shape: cylinder
    style: {fill: "#FFF4D6"; stroke: "#B7791F"}
  }
  ext: {
    style: {fill: "#F2F4F7"; stroke: "#667085"; stroke-dash: 3}
  }
}

customer: Customer {shape: person}

aws: AWS {
  gw: API gateway {class: svc}
  orders: Orders service {class: svc}
  pay: Payments service {class: svc}
  bus: Event bus {shape: queue}
  db: Orders DB {class: store}

  gw -> orders
  orders -> db: SQL
  orders -> bus: OrderPlaced
  bus -> pay
}

stripe: Stripe {class: ext}

customer -> aws.gw: HTTPS
aws.pay -> stripe: charge

start: Request received {shape: oval}
auth: Logged in? {shape: diamond}
login: Redirect to login
cached: In cache? {shape: diamond}
serve: Serve cached page
render: Render page
store: Save to cache
done: Send response {shape: oval}

start -> auth
auth -> login: no
auth -> cached: yes
cached -> serve: yes
cached -> render: no
render -> store -> done
serve -> done
login -> done

shape: sequence_diagram

# Declare actors first: this fixes their left-to-right order
user: User {shape: person}
web: Web app
api: API
stripe: Stripe
db: DB

user -> web: Click "Pay"
web -> api: POST /orders
api -> api: validate cart

# A nested key on an actor = a span (activation bar)
api.tx -> db: INSERT order
db -> api.tx: ok

# A container with no connections of its own = a group
payment: Payment {
  api -> stripe: charge
  stripe -> api: succeeded
}

# A nested key with no connections = a note
api."Idempotency key prevents double charges"

api -> web: 201 Created
web -> user: Show receipt

vars: {
  d2-config: {
    # ELK and TALA point foreign keys at the exact row
    layout-engine: elk
  }
}
direction: right

users: {
  shape: sql_table
  id: int {constraint: primary_key}
  email: varchar {constraint: unique}
  created_at: timestamp
}

orders: {
  shape: sql_table
  id: int {constraint: primary_key}
  user_id: int {constraint: foreign_key}
  status: varchar
  total_cents: int
}

order_items: {
  shape: sql_table
  order_id: int {constraint: [primary_key; foreign_key]}
  product_id: int {constraint: [primary_key; foreign_key]}
  qty: int
}

products: {
  shape: sql_table
  id: int {constraint: primary_key}
  name: varchar
  price_cents: int
}

# <-> so that both ends can carry an arrowhead
orders.user_id <-> users.id
order_items.order_id <-> orders.id
order_items.product_id <-> products.id

# Crow's feet on every relationship. ** reaches nested rows,
# a plain * would only match top-level tables
(** <-> **)[*]: {
  source-arrowhead.shape: cf-many
  target-arrowhead.shape: cf-one-required
}

platform: Product platform {
  grid-rows: 4
  grid-gap: 0

  clients: Clients {
    grid-columns: 3
    Web; iOS; Android
  }
  gateway: API gateway
  services: Services {
    grid-columns: 4
    Orders; Billing; Search; Notifications
  }
  data: Data {
    grid-columns: 2
    Postgres: {shape: cylinder}
    Kafka: {shape: queue}
  }
}

direction: right
dev: Developer {shape: person}
ci: CI
registry: Registry
cluster: Cluster

# Each step inherits everything from the step before it
steps: {
  1: {
    dev -> ci: git push
  }
  2: {
    ci -> registry: image
  }
  3: {
    registry -> cluster: deploy
    cluster.style.fill: "#DCFCE7"
  }
}

# models: define everything once...
aws: {
  api; db; cache
  api -> db
  api -> cache
}
users -> aws.api

# ...hide everything...
**: suspend
(** -> **)[*]: suspend

# ...then bring back only what this view needs
aws.api: unsuspend
aws.db: unsuspend
(aws.api -> aws.db)[*]: unsuspend

Gotchas

What you'll see, and what to do about it. Several of these came up while preparing this page.

You get duplicate shapes

A connection used a label instead of a key (Backend -> db when the key is be). Connect keys. Docs

A style or line after # vanished

# starts a comment. Quote hex colors: fill: "#FFF4D6". Docs

"substitutions must begin on {"

A $ inside double quotes starts a ${…} substitution. Use single quotes: 'Price: $5'. Docs

A source arrowhead doesn't show

a -> b has no source end. Use <-> when both ends need an arrowhead. Docs

A glob ignores nested shapes

* matches only the current level. Use ** to recurse, *** to also reach layers and imports. Docs

v1.2 became a container

Dots are paths. Quote keys that contain dots: "v1.2". Docs

label or shape used as a column name

Reserved words need quotes: "label": string. Docs

API and api are the same shape

Keys are case-insensitive. Change the label, not the key's case. Docs

A sequence group can't find an actor

In sequence diagrams, actors referenced in a group must be declared at the top level first. Docs

direction on a container does nothing

Per-container direction works only with TALA. Other engines use the root direction. Docs

Container-to-child edge fails

Dagre can't connect a container to its own descendant. Switch to ELK or TALA. Docs

The TALA layout changed completely

TALA has randomness, so small edits can reshuffle it. Pin key shapes with top + left or tune --tala-seeds. Docs

A repeated connection didn't update the first

Repeating a -> b creates a new edge. Edit an existing one with (a -> b)[0].style…. Docs

CLI and config

Precedence: flags and environment variables beat d2-config. Putting the config in the file is still the best default, because the diagram then renders the same for everyone. Full list: CLI manual or man d2.

Where to go next

Once this page has you started, pick the path that matches what you need.

Asking an agent

D2 is younger than Mermaid or PlantUML, so models sometimes mix in syntax from those, or features from older versions. Naming the version and the engine up front avoids most of that, and running d2 validate on the answer catches the rest.

I'm writing a D2 diagram (D2 v0.9, rendered with the CLI).
Layout engine: [dagre | elk | tala]
Diagram type: [architecture | flowchart | sequence | ERD | grid]

What it should show:
[describe the parts and how they connect]

Constraints:
- Short keys, human-readable labels; connections use keys.
- Put styling in `classes`, not on each shape.
- Quote hex colors; put config in vars.d2-config.
- Only use features supported by my layout engine.

Return the complete .d2 file, then list any keyword
you used that isn't basic syntax and what it does.

References

Written October 2026 against D2 0.9.0 (released September 7, 2026). Every snippet on this page was compiled with that version. Note the project moved from terrastruct/d2 to d2lang/d2; older articles link to the previous home.