# Install

> What vawe needs, how to install it from source, and how to fix the failures that `doctor` finds.

Canonical: https://vawe.dev/docs/install

By the end of this page, `bin/vawe doctor` reports no missing tool and you can render a <Term id="draft">draft</Term>. vawe runs from a source checkout. It has no installer.

## Requirements

`bin/vawe doctor` checks these seven items. The list comes from `harness/dev/doctor.mjs`.

| Item                             | Needed | What it is for                                                           |
| -------------------------------- | ------ | ------------------------------------------------------------------------ |
| Node 22 or newer                 | yes    | Runs `bin/vawe` and the renderer.                                        |
| git                              | yes    | Version control for the checkout.                                        |
| ffmpeg with libx264 and drawtext | yes    | Encodes the frames and mixes the audio.                                  |
| ffprobe                          | yes    | Part of the ffmpeg package.                                              |
| puppeteer Chrome                 | yes    | Draws every frame of the page.                                           |
| `assets/fonts`                   | yes    | The free font faces. The folder must hold files.                         |
| tesseract                        | no     | OCR for `vawe see` (also `see --spec`) and `vawe check coverage --text`. |

## Install

<Steps>
  <Step>
    ### Install the outside tools

    Install Node 22 or newer, git and ffmpeg with your system package manager. On macOS with Homebrew:

    ```bash
    brew install node git ffmpeg
    ```

    Add `tesseract` if you want OCR. `doctor` prints the exact line for Debian, Ubuntu, Fedora, Arch, Alpine, openSUSE and Windows.
  </Step>

  <Step>
    ### Clone vawe and install the packages

    ```bash
    git clone https://github.com/vawe-hq/vawe.git && cd vawe
    npm install
    npx puppeteer browsers install chrome
    ```

    The puppeteer postinstall step downloads a full Chrome. The third command installs it again when the download was skipped. The `npm install` ends with `doctor`.
  </Step>

  <Step>
    ### Run `doctor`

    ```bash
    bin/vawe doctor
    ```

    When all is well, you see one line: `ok, 7 checks (macOS)`. The system name changes with your system. The exit code is 0.
  </Step>
</Steps>

## The `doctor` verb

`vawe doctor` probes each tool, and for each missing tool it prints one line with the cause and one `fix:` line. It exits with code 1 only when a required tool is missing. A missing optional tool prints `optional` and does not change the exit code.

| Flag      | What it does                                                   |
| --------- | -------------------------------------------------------------- |
| `--quiet` | Prints only problems and writes `.vawe/doctor.json`.           |
| `--json`  | Prints `[{tool, required, ok, version, fix}]` instead of text. |

The output for a Node that is too old, on macOS, has this form. `<version>` is the version that `doctor` finds.

```text
MISSING  node 22+: found v<version>, need 22 or newer
         fix: brew install node
1 required tool(s) missing.
```

The postinstall step runs `doctor --quiet`, so the result is in `.vawe/doctor.json` after an install.

## If it fails

| What you see                                              | Why                                                  | What to do                                                                               |
| --------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `found v<version>, need 22 or newer`                      | Node is too old.                                     | Install Node 22 or newer.                                                                |
| `ffmpeg not on PATH`                                      | ffmpeg is not installed, or not in `PATH`.           | Run the `fix:` line of `doctor`.                                                         |
| `this ffmpeg build cannot run libx264 encode or drawtext` | The ffmpeg build lacks an encoder or a filter.       | Install a full ffmpeg build. On Fedora and RHEL, enable the RPM Fusion repository first. |
| `puppeteer has no Chrome download`                        | The install skipped the Chrome download.             | Run `npm install`, then `npx puppeteer browsers install chrome`.                         |
| `Chrome did not launch: ...`                              | Chrome downloaded but does not start on this system. | Read the text after the colon. It is the first line of the Chrome error.                 |
| `assets/fonts is missing`                                 | The font folder is empty or absent.                  | Run `git checkout -- assets/fonts`, or `node generators/media/fonts.mjs`.                |

> Output can differ between hosts that rasterise on a different GPU or Chrome version.

## What to read next

- []()" title="Quickstart" href="/docs/quickstart">
    Start a film and render a draft.
  </Card>

- []()" title="Use with an agent" href="/docs/agents">
    Set up Claude Code, Codex or Cursor.
  </Card>

{/* sources (vawe d8481cc61):
  requirements table, seven checks, required flags, optional tesseract: harness/dev/doctor.mjs TOOLS list; OCR users: bin/vawe see --help (--no-ocr, --spec), harness/media/coverage.mjs --text
  Node 22: harness/dev/doctor.mjs probeNode; README.md "Install"
  doctor flags, exit code: bin/vawe doctor --help; harness/dev/doctor.mjs header
  output format: harness/dev/doctor.mjs report block and probeNode (found ${process.version}, need 22 or newer); brew line: MANAGERS.brew + TOOLS node pkg
  ok line: harness/dev/doctor.mjs final report block
  postinstall (doctor --quiet), puppeteer note: package.json "scripts" and "//puppeteer-note"; clone URL and Chrome command: README.md "Quickstart"
  .vawe/doctor.json: harness/dev/doctor.mjs RESULT_FILE
  fix lines, RPM Fusion: harness/dev/doctor.mjs TOOLS (pkg dnf)
  host differences: README.md "Install"
  */}