1# install
2
3You may install `d2` through any of the following methods.
4
5<!-- toc -->
6- [install.sh](#installsh)
7 - [Security](#security)
8- [macOS (Homebrew)](#macos-homebrew)
9- [Linux](#linux)
10 - [Void Linux](#void-linux)
11- [Standalone](#standalone)
12 - [Manual](#manual)
13 - [PREFIX](#prefix)
14- [From source](#from-source)
15 - [Source Release](#source-release)
16- [Windows](#windows)
17 - [Release archives](#release-archives)
18 - [WSL](#wsl)
19- [Docker](#docker)
20- [Coming soon](#coming-soon)
21
22## install.sh
23
24The recommended and easiest way to install is with our install script, which will detect
25the OS and architecture you're on and use the best method:
26
27```sh
28# With --dry-run the install script will print the commands it will use
29# to install without actually installing so you know what it's going to do.
30curl -fsSL https://d2lang.com/install.sh | sh -s -- --dry-run
31# If things look good, install for real.
32curl -fsSL https://d2lang.com/install.sh | sh -s --
33```
34
35For help on the terminal run, including the supported package managers and detection
36methods:
37
38```sh
39curl -fsSL https://d2lang.com/install.sh | sh -s -- --help
40```
41
42### Security
43
44The install script is not the most secure way to install d2. We recommend that if
45possible, you use your OS's package manager directly or install from source with `go` as
46described below.
47
48But this does not mean the install script is insecure. There is no major flaw that
49the install script is more vulnerable to than any other method of manual installation.
50The most secure installation method involves a second independent entity, i.e your OS
51package repos or Go's proxy server.
52
53We're careful shell programmers and are aware of the many footguns of the Unix shell. Our
54script was written carefully and with detail. For example, it is not vulnerable to partial
55execution and the entire script runs with `set -eu` and very meticulous quoting.
56
57It follows the XDG standards, installs `d2` properly into a Unix hierarchy path
58(`/usr/local` unless `/usr/local` requires sudo in which case `~/.local` is used) and
59allows for easy uninstall. You can easily adjust the used path with `--prefix`.
60
61Some other niceties are that it'll tell you if you need to adjust `$PATH` or `$MANPATH` to
62access `d2` and its manpages. It can also install
63[TALA](https://github.com/terrastruct/tala) for you with `--tala`. You can also use it to
64install a specific version of `d2` with `--version`. Run it with `--help` for more more
65detailed docs on its various options and features.
66
67If you're still concerned, remember you can run with `--dry-run` to avoid writing anything.
68
69The install script does not yet verify any signature on the downloaded release
70but that is coming soon. [#315](https://github.com/terrastruct/d2/issues/315)
71
72## macOS (Homebrew)
73
74If you're on macOS, you can install with `brew`.
75
76```sh
77brew install d2
78```
79
80> The install script above does this automatically if you have `brew` installed and
81> are running it on macOS.
82
83You can also install from source with:
84
85```d2
86brew install d2 --HEAD
87```
88
89## Linux
90
91The following distributions have packages for d2:
92
93### Void Linux
94
95All supported platforms:
96
97```sh
98xbps-install d2
99```
100
101## Standalone
102
103We publish standalone release archives for every release on Github.
104
105Here's a minimal example script that downloads a standalone release, extracts it into the
106current directory and then installs it.
107Adjust VERSION, OS, and ARCH as needed.
108
109```sh
110VERSION=v0.0.13 OS=macos ARCH=amd64 curl -fsSLO \
111 "https://github.com/terrastruct/d2/releases/download/$VERSION/d2-$VERSION-$OS-$ARCH.tar.gz" \
112 && tar -xzf "d2-$VERSION-$OS-$ARCH.tar.gz" \
113 && make -sC "d2-$VERSION" install
114```
115
116To uninstall:
117
118```sh
119VERSION=v0.0.13 make -sC "d2-$VERSION" uninstall
120```
121
122### Manual
123
124You can also manually download the `.tar.gz` release for your OS/ARCH combination and then
125run the following inside the extracted directory to install:
126
127```sh
128make install
129```
130
131Run the following to uninstall:
132
133```sh
134make uninstall
135```
136
137### PREFIX
138
139You can control the Unix hierarchy installation path with `PREFIX=`. For example:
140
141```sh
142# Install under ~/.local.
143# Binaries will be at ~/.local/bin
144# And manpages will be under ~/.local/share/man
145# And supporting data like icons and fonts at ~/.local/share/d2
146make install PREFIX=$HOME/.local
147```
148
149The install script places the standalone release into `$PREFIX/lib/d2/d2-<version>`
150and we recommend doing the same with manually installed releases so that you
151know where the release directory is for easy uninstall.
152
153## From source
154
155You can always install from source:
156
157```sh
158go install oss.terrastruct.com/d2@latest
159```
160
161You need at least Go v1.20
162
163### Source Release
164
165To install a release from source clone the repository and then:
166
167```sh
168./ci/release/build.sh --install
169# To uninstall:
170# ./ci/release/build.sh --uninstall
171```
172
173Installing a real release will also install manpages and in the future other assets like
174fonts and icons. Furthermore, when installing a non versioned commit, installing a release
175will ensure that `d2 --version` works correctly by embedding the commit hash into the `d2`
176binary.
177
178Remember, you need at least Go v1.20
179
180## Windows
181
182We have prebuilt [releases](https://github.com/terrastruct/d2/releases) of d2 available for Windows via `.msi` installers. The installer
183will add the `d2` binary to your `$PATH` so that you can execute `d2` in `cmd.exe` or
184`pwsh.exe`.
185
186### Release archives
187
188We also have release archives for Windows structured in the same way as our Unix releases
189for use with MSYS2.
190
191<img width="1680" alt="Screenshot 2022-12-06 at 2 55 27 AM" src="https://user-images.githubusercontent.com/10180857/205892927-6f3e116c-1c4a-440a-9972-82c306aa9779.png">
192
193See [MSYS2](https://www.msys2.org/) or [Git Bash](https://gitforwindows.org/#bash) (Git
194Bash is based on MSYS2).
195
196MSYS2 provides a unix style shell environment that is native to Windows (unlike
197[Cygwin](https://www.cygwin.com/)). MSYS2 allows `install.sh` to work, enables automatic
198installation of our standalone releases via `make install` and makes the manpage
199accessible via `man d2`.
200
201The MSYS2 terminal also enables `d2` to display colors like in the above screenshot.
202
203In addition, all of our development and CI scripts work under MSYS2 whereas they do not
204under plain Windows.
205
206### WSL
207
208`d2` works perfectly under [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)
209aka Windows Subsystem for Linux if that's what you prefer. Installation is just like any
210other Linux system.
211
212## Docker
213
214https://hub.docker.com/repository/docker/terrastruct/d2
215
216We publish `amd64` and `arm64` images based on `debian:latest` for each release.
217
218Example usage:
219
220```sh
221echo 'x -> y' >helloworld.d2
222docker run --rm -it -u "$(id -u):$(id -g)" -v "$PWD:/home/debian/src" \
223 -p 127.0.0.1:8080:8080 terrastruct/d2:v0.1.2 --watch helloworld.d2
224# Visit http://127.0.0.1:8080
225```
226
227## Coming soon
228
229- rpm and deb packages
230 - with repositories and standalone
231- homebrew core
View as plain text