# Download and run locally

> Download the built extension or its source from code.extension.dev as a zip, and run the build in a browser on your machine with one command.

Canonical: https://docs.extension.dev/code/download-and-run
This page as Markdown: https://docs.extension.dev/code/download-and-run.md
Section: Code
Siblings: [AI generation](https://docs.extension.dev/code.md) · [Terminal](https://docs.extension.dev/code/terminal.md) · [Chat mode](https://docs.extension.dev/code/chat-mode.md) · [Starters and templates](https://docs.extension.dev/code/starters.md) · [Live preview](https://docs.extension.dev/code/preview.md) · [Select to edit](https://docs.extension.dev/code/select-to-edit.md) · [The Code tab](https://docs.extension.dev/code/code-tab.md) · [Build console](https://docs.extension.dev/code/build-console.md) · [Checkpoints](https://docs.extension.dev/code/checkpoints.md) · [Drafts](https://docs.extension.dev/code/drafts.md) · [Firefox engine](https://docs.extension.dev/code/firefox-engine.md) · [Share links](https://docs.extension.dev/code/share.md) · [Publish and import](https://docs.extension.dev/code/publish.md) · [Generation allowance](https://docs.extension.dev/code/allowance.md) · [Settings and sign-in](https://docs.extension.dev/code/settings.md)
Map of every page: https://docs.extension.dev/llms.txt · Whole corpus: https://docs.extension.dev/llms-full.txt

---

# Download and run locally

Download hands you the extension as a zip, and Run in a real browser hands
you the command that loads it on your machine. Reach for them when the
preview is not enough and you want the extension in a browser of your own.

## Quick start

```bash
npx -y extension@latest preview --browser=chrome
```

Press **Download** in the header and pick **Built extension (.zip)**. Unzip
it and load the folder from `chrome://extensions` with **Load unpacked**, or
run the command above in the unzipped folder to open a browser with the
extension loaded.


## How it works

### Two zips

The **Download** dialog has two rows. **Built extension (.zip)** is what the
runner shows: the compiled files plus a `README.txt` with the load unpacked
steps, saved as `<name>-chrome.zip`. **Source (.zip)** is what the editor
holds, every file as written, saved as `<name>-source.zip`.

The two are not the same thing. Chrome compiles nothing, so a project written
in TypeScript or React loads from the built zip and not from the source zip.
With the Firefox engine active the dialog shows the built name as
`<name>-firefox.zip`, and the zip holds the Chromium build.

Download needs no sign-in and no allowance. It keeps working when generation
is locked.

### The agent's download

`download` is the agent's command. Typed bare it prints a notice pointing to
the header control. Asked for, the agent runs `download` or `download
source`, which saves the zip into `.out/` in the workspace and hands it to
the browser as a download. `.out/` never syncs to your draft.

### Run in a real browser

The **Run in a real browser** control opens a dialog with a short clip and
the command. Before a publish, the command is `npx -y extension@latest
preview --browser=chrome`, run in the unzipped built folder. After a
publish, the command points at the published zip:

```bash
npx -y extension@latest preview <zipUrl> --browser=chrome
```

That runs the build in a fresh browser profile on your machine with
Extension.js, the open source framework Extension.dev sponsors. It needs no
account.

`run-in-chrome` is the agent's command for the same handoff. Before a
publish it prints the two steps, publish then preview. After one it prints
the command with the zip URL filled in.

## Reference

| Row | File | Contents |
| --- | --- | --- |
| Built extension (.zip) | `<name>-chrome.zip` | The compiled build plus `README.txt` |
| Source (.zip) | `<name>-source.zip` | Every file as written |

| Command | What it does |
| --- | --- |
| `download` or `download dist` | The agent saves the built zip into `.out/` |
| `download source` | The agent saves the source zip into `.out/` |
| `run-in-chrome` | The agent prints the `npx` handoff |
| `npx -y extension@latest preview --browser=chrome` | Runs the unzipped build in a fresh browser on your machine |

## When it fails

- **Chrome refuses the source zip.** It holds TypeScript or JSX that Chrome
  cannot run. Load the built zip instead.
- **The agent answers "No compiled build yet".** Run `build` first, then ask
  for the download again.
- **Typing `download` in the terminal only prints a notice.** The bare word
  is the agent's command. Use **Download** in the header, or ask the agent to
  download the source.
- **The file is named chrome although the Firefox engine is active.** The
  built zip is always the Chromium build. The Gecko adaptation happens in the
  preview only.

## Next

- [Publish and import](/code/publish) for the zip URL the command points at
- [Share links](/code/share) for a preview a reviewer opens without
  installing anything
- [Firefox engine](/code/firefox-engine) for Gecko's verdict before you run
  it locally