1 files changed, 111 insertions, 0 deletions
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 000000000..48d3e188c
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,111 @@
+Bun ships as a single executable that can be installed a few different ways.
+
+{% callout %}
+**Windows users** — Bun does not currently provide a native Windows build. We're working on this; progress can be tracked at [this issue](https://github.com/oven-sh/bun/issues/43). In the meantime, use one of the installation methods below for Windows Subsystem for Linux.
+
+**Linux users** — Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1.
+{% /callout %}
+
+{% codetabs %}
+
+```bash#Native
+$ curl -fsSL https://bun.sh/install | bash # for macOS, Linux, and WSL
+```
+
+```bash#npm
+$ npm install -g bun # the last `npm` command you'll ever need
+```
+
+```bash#Homebrew
+$ brew tap oven-sh/bun # for macOS and Linux
+$ brew install bun
+```
+
+```bash#Docker
+$ docker pull oven/bun:edge
+$ docker run --rm --init --ulimit memlock=-1:-1 oven/bun:edge
+```
+
+{% /codetabs %}
+
+## Upgrading
+
+Once installed, the binary can upgrade itself.
+
+```sh
+$ bun upgrade
+```
+
+{% callout %}
+**Homebrew users** — To avoid conflicts with Homebrew, use `brew upgrade bun` instead.
+{% /callout %}
+
+Bun automatically releases an (untested) canary build on every commit to `main`. To upgrade to the latest canary build:
+
+```sh
+$ bun upgrade --canary
+```
+
+[View canary build](https://github.com/oven-sh/bun/releases/tag/canary)
+
+<!--
+## Native
+
+Works on macOS x64 & Silicon, Linux x64, Windows Subsystem for Linux.
+
+```sh
+$ curl -fsSL https://bun.sh/install | bash
+```
+
+Once installed, the binary can upgrade itself.
+
+```sh
+$ bun upgrade
+```
+
+Bun automatically releases an (untested) canary build on every commit to `main`. To upgrade to the latest canary build:
+
+```sh
+$ bun upgrade --canary
+```
+
+## Homebrew
+
+Works on macOS and Linux
+
+```sh
+$ brew tap oven-sh/bun
+$ brew install bun
+```
+
+Homebrew recommends using `brew upgrade <package>` to install newer versions.
+
+## Docker
+
+Works on Linux x64
+
+```sh
+# this is a comment
+$ docker pull oven/bun:edge
+this is some output
+$ docker run --rm --init --ulimit memlock=-1:-1 oven/bun:edge
+$ docker run --rm --init --ulimit memlock=-1:-1 oven/bun:edge
+this is some output
+``` -->
+
+## Completions
+
+Shell auto-completion should be configured automatically when Bun is installed.
+
+If not, run the following command. It uses `$SHELL` to determine which shell you're using and writes a completion file to the appropriate place on disk. It's automatically re-run on every `bun upgrade`.
+
+```bash
+$ bun completions
+```
+
+To write the completions to a custom location:
+
+```bash
+$ bun completions > path-to-file      # write to file
+$ bun completions /path/to/directory  # write into directory
+```