Getting started

This page covers building Deno from source, running the dev binary, and the most common iteration loops. It is the contributor's quick-start; the user-facing install instructions live in the README and at docs.deno.com.

Prerequisites

Deno is built with stable Rust pinned by rust-toolchain.toml. The project also depends on a handful of native build tools because it pulls in V8 and other C/C++ libraries.

Requirement	Notes
Rust	Pinned in rust-toolchain.toml. rustup will install the right version on first build.
cmake	Needed by V8 and several *-sys crates
protobuf	protoc is needed by prost-based deps
python3	Used by the V8 build scripts
C/C++ toolchain	clang on macOS, build-essential on Linux, MSVC Build Tools on Windows
Git submodules	Test data lives in submodules; clone with --recurse-submodules

The full prerequisite matrix per OS is in .github/CONTRIBUTING.md.

Cloning

Use a recursive clone — Deno's spec tests, WPT, and node_compat tests live in submodules under tests/:

git clone --recurse-submodules https://github.com/denoland/deno.git
cd deno

If you forgot --recurse-submodules, run git submodule update --init --recursive afterward.

The ./x developer CLI

The repo ships a Deno-script developer CLI at ./x (source: tools/x.ts). It wraps the most common cargo + lint + test workflows:

./x build       # debug build of the deno binary
./x check       # cargo check (no link)
./x fmt         # format JS/TS + Rust + markdown
./x lint        # lint JS/TS + Rust
./x lint-js     # lint JS/TS only (faster)
./x verify      # fmt + lint-js (used as a pre-commit gate)
./x test        # runtime unit tests
./x node-test   # Node API unit tests
./x node-compat # Node compat suite
./x spec        # spec/integration tests under tests/specs/
./x napi        # NAPI native addon tests

Run ./x --help for the full list. The Cargo subcommands and tools/format.js / tools/lint.js still work directly if you prefer them.

Building

# Debug build of just the deno binary (fastest)
cargo build --bin deno

# Full debug build (workspace)
cargo build

# Release build
cargo build --release

The compiled binary lands at target/debug/deno or target/release/deno. A typical first build downloads V8 prebuilts (or builds V8 from source if V8_FROM_SOURCE=1), so expect anywhere from ten minutes to an hour the first time.

Running your dev build

./target/debug/deno --version
./target/debug/deno run example.ts
./target/debug/deno run --allow-net --allow-read script.ts

To iterate on JS/TS that ships inside the runtime (the *.js files in ext/* and cli/js/) without rebuilding, use the hmr feature flag:

cargo build --features hmr --bin deno
cargo run --features hmr -- run example.ts

In HMR mode the JS sources are read off disk at startup instead of being baked into a snapshot. Add the same feature to your editor's rust-analyzer config so types resolve correctly:

// .vscode/settings.json
{
  "rust-analyzer.cargo.features": ["hmr"],
  "deno.importMap": "tools/core_import_map.json",
}

Running tests

# All tests (slow)
cargo test

# Just the spec tests
cargo test specs

# A single spec test by name
cargo test specs::run::script_basic

# Tests for a specific package
cargo test -p deno_core
cargo test -p deno_runtime

Spec tests live under tests/specs/ and are described by __test__.jsonc files. Each test is a CLI invocation whose stdout/stderr is matched against .out files using a small wildcard matcher ([WILDCARD], [WILDLINE], [UNORDERED_START]/[UNORDERED_END]). See Testing for details.

Format and lint before committing

./x verify is the pre-commit gate; the CI workflow .github/workflows/ci.generated.yml runs the same checks. The two underlying tools:

• tools/format.js — runs dprint (JS/TS/markdown/JSON) and cargo fmt (Rust).
• tools/lint.js — runs deno lint with the custom rules in tools/lint_plugins/ plus cargo clippy.

If you only touched JS/TS, ./x lint-js is dramatically faster than the full lint.

Common build issues

• error: linking with cc failed — install your platform's C/C++ toolchain. On Linux apt install build-essential cmake protobuf-compiler.
• V8 download fails — check the proxy/firewall. As a workaround set V8_FROM_SOURCE=1 to build V8 yourself.
• Stale snapshot mismatch — run cargo clean -p deno and rebuild after pulling. Snapshots are cached per-build and occasionally drift.
• cmake: command not found — install cmake 3.x; some *-sys crates need it even for prebuilt V8.

For deeper debugging tips see Debugging.