D2 (Declarative Diagramming)

D2는 text로 diagram의 object와 관계를 선언하고 SVG, PNG, PDF 등의 결과물로 render하는 open-source diagram scripting language와 CLI이다.

• .d2 source file은 일반 text이므로 Git diff, code review, 재사용, 자동화에 적합하다.
• shape, connection, container, class, sequence diagram, SQL table, Markdown, LaTeX, icon 등을 표현할 수 있다.
• 기본 layout engine은 dagre이며 ELK, 선택 설치하는 TALA도 사용할 수 있다.
• output path를 생략하면 input과 같은 이름의 .svg를 생성한다.
• –watch mode는 source 변경을 감시하고 browser에서 diagram을 live reload한다.

공식 문서는 Unix 계열에서 installer script를 가장 간단한 방법으로 안내한다. 먼저 –dry-run으로 실행 내용을 검토할 수 있다.

D2 전용 공식 APT repository나 .deb package는 제공되지 않는다. 공식 installer 또는 release archive를 사용한다.

# 실행할 작업만 확인
curl -fsSL https://d2lang.com/install.sh | sh -s -- --dry-run
 
# 설치
curl -fsSL https://d2lang.com/install.sh | sh -s --

D2 전용 공식 DNF/YUM repository나 .rpm package는 제공되지 않는다. Linux 공통 공식 installer 또는 release archive를 사용한다.

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

brew install d2

공식 Windows release는 MSI installer를 제공하며 Windows Package Manager에서도 설치할 수 있다.

winget install --id Terrastruct.D2 --exact

Go가 이미 설치되어 있다면 source에서 CLI만 설치할 수 있다. 이 방식은 man page를 설치하지 않는다.

go install oss.terrastruct.com/d2@latest
 
# 설치 확인
d2 version

d2 input.d2
d2 input.d2 output.svg
d2 --watch input.d2 output.svg
d2 validate input.d2
d2 fmt input.d2

• d2 [OPTIONS] INPUT [OUTPUT]: D2 source를 compile하고 diagram으로 render
• d2 validate FILE.d2: source syntax와 semantic validation 수행
• d2 fmt [–check] FILE.d2…: source format 적용 또는 검사
• d2 layout [ENGINE]: 사용 가능한 layout engine 또는 engine별 option 확인
• d2 themes: 사용 가능한 theme 목록 출력
• d2 play FILE.d2: source를 online Playground에서 열기

• -w, –watch: input 변경 감시와 browser live reload
• -l, –layout ENGINE: dagre, elk, tala 등 layout 선택
• -t, –theme ID: light mode theme 지정
• –dark-theme ID: dark mode theme 지정
• -s, –sketch: 손으로 그린 듯한 style 적용
• –pad PIXELS: diagram 주변 여백 지정
• –scale FACTOR: output scale 지정
• –target BOARD: composition에서 render할 board 선택
• –stdout-format FORMAT: stdout output을 svg, png, ascii 중에서 선택
• –timeout SECONDS: render 제한 시간 지정
• –version: version 출력

input.d2 파일을 작성한다.

client -> api: HTTPS
api -> database: SQL

SVG로 render한다.

d2 input.d2
# input.svg 생성

direction: right
 
user: User {
  shape: person
}
 
cloud: Production {
  web: Web API
  db: PostgreSQL {
    shape: cylinder
  }
  web -> db: query
}
 
user -> cloud.web: request {
  style.stroke: "#4c78a8"
  style.stroke-width: 2
}

Hex color는 #가 comment로 해석되지 않도록 quote로 감싼다.

d2 --watch input.d2 output.svg
 
# browser를 열지 않고 지정 address에서 watch server 실행
d2 --watch --browser 0 --host 127.0.0.1 --port 8080 input.d2 output.svg

# 설치된 layout과 theme 확인
d2 layout
d2 themes
 
# ELK layout과 light/dark theme로 render
d2 --layout elk --theme 300 --dark-theme 200 input.d2 output.svg
 
# sketch style
d2 --sketch input.d2 sketch.svg

d2 validate architecture.d2
d2 fmt architecture.d2
 
# CI에서 format 변경 없이 검사
d2 fmt --check architecture.d2

Build pipeline은 output file 존재 여부가 아니라 d2 process의 exit status로 성공을 판단한다. Render error가 발생해도 반복 작업을 돕기 위한 partial output이 남을 수 있다.

printf 'x -> y\n' | d2 - - > output.svg
printf 'x -> y\n' | d2 --stdout-format ascii - -

Input 또는 output에 -를 사용하면 stdin 또는 stdout을 뜻한다. Stdout의 기본 format은 SVG이다.

• SVG: 기본 format. output을 생략하면 input 이름을 가진 .svg 생성
• PNG: headless browser를 사용하므로 첫 실행에서 Playwright dependency를 내려받을 수 있음
• PDF: PNG render dependency를 공유하며 link를 유지할 수 있음
• PPTX: layer, scenario, step composition을 presentation으로 내보낼 때 유용
• GIF: 여러 board를 짧은 animation으로 표현할 때 사용
• ASCII: .txt extension 또는 –stdout-format ascii로 생성하는 beta 기능

d2 input.d2 output.png
d2 input.d2 output.pdf
d2 input.d2 output.pptx
d2 input.d2 output.gif
d2 input.d2 output.txt

많은 CLI flag는 environment variable 또는 source의 vars.d2-config로 고정할 수 있다.

vars: {
  d2-config: {
    layout-engine: elk
    theme-id: 300
    dark-theme-id: 200
    pad: 40
  }
}

대표 environment variable:

• D2_LAYOUT: layout engine
• D2_THEME: light theme ID
• D2_DARK_THEME: dark theme ID
• D2_PAD: diagram padding
• D2_WATCH: watch mode
• HOST, PORT: watch server address

CLI flag와 environment variable은 source의 d2-config보다 우선한다. Project에서는 실행 환경마다 결과가 달라지지 않도록 설정 방식을 통일하고 generated artifact도 검토한다.

• d2: command not found: installer가 출력한 PATH 안내를 적용하고 새 shell에서 d2 version을 확인한다.
• PNG/PDF render에서 Chromium 실행 오류: 공식 export 문서가 안내하는 Playwright system dependency를 OS에 맞게 설치한다.
• 큰 diagram이 timeout됨: source를 분리하거나 –timeout 값을 늘리고 layout engine을 비교한다.
• layout 결과가 기대와 다름: d2 layout과 d2 layout ENGINE으로 지원 option을 확인한다. Layout engine마다 지원하는 위치·크기 기능이 다르다.
• SVG가 vector editor에서 다르게 보임: D2 SVG는 CSS와 Markdown용 HTML foreignObject를 포함할 수 있어 browser/web embedding을 우선 대상으로 한다.
• CI가 실패했는데 output이 존재함: partial render일 수 있으므로 반드시 exit status를 확인한다.

• 공식 release는 Linux와 macOS의 amd64/arm64 archive, Windows installer와 archive를 제공한다.
• dagre는 기본 engine이고 ELK는 복잡한 directed graph에 사용할 수 있다. TALA는 별도 license와 설치가 필요한 선택 engine이다.
• ASCII export는 beta이며 ELK와 TALA에서만 render된다. Dagre를 지정하거나 layout을 생략하면 ASCII output에는 ELK가 사용된다.
• PNG와 그 파생 format은 headless browser dependency가 필요할 수 있지만 SVG render에는 같은 dependency가 필요하지 않다.

d2 --help

이 환경에는 d2 binary가 설치되어 있지 않아 live help를 실행하지 않았다.
현재 option과 subcommand는 D2 official CLI manual을 참고한다.

• D2 official website
• D2 Tour
• D2 CLI manual
• D2 export formats
• D2 GitHub repository
• D2 Playground

• codex:: 2026-08-04 Added D2 installation, declarative syntax, rendering, watch mode, layout, export, configuration, validation, and troubleshooting guidance.