Installation

Prerequisites

Perry compiles TypeScript to native binaries by linking with your system’s C toolchain, so every install path needs a linker:

• macOS: Xcode Command Line Tools (xcode-select --install)
• Linux: gcc or clang (apt install build-essential on Debian/Ubuntu, apk add build-base on Alpine)
• Windows: LLVM (winget install LLVM.LLVM) + perry setup windows (lightweight, ~1.5 GB, no Visual Studio needed), or MSVC Build Tools with the “Desktop development with C++” workload — see the Windows platform guide for both options

The source install additionally needs the Rust toolchain via rustup.

Install Perry

npm / npx (recommended — any platform)

Perry ships as a prebuilt-binary npm package. This is the fastest way to get started and the only path that covers all seven supported platforms (macOS arm64/x64, Linux x64/arm64 glibc + musl, Windows x64) with a single command:

# Project-local (pins Perry's version alongside your deps)
npm install @perryts/perry
npx perry compile src/main.ts -o myapp && ./myapp

# Global
npm install -g @perryts/perry
perry compile src/main.ts -o myapp

# Zero-install, one-shot
npx -y @perryts/perry compile src/main.ts -o myapp

@perryts/perry is a thin launcher; npm automatically picks the matching prebuilt via optionalDependencies (@perryts/perry-darwin-arm64, @perryts/perry-linux-x64-musl, etc.) based on your os / cpu / libc. Requires Node.js ≥ 16.

Homebrew (macOS)

brew install perryts/perry/perry

winget (Windows)

winget install PerryTS.Perry

APT (Debian / Ubuntu)

curl -fsSL https://perryts.github.io/perry-apt/perry.gpg.pub | sudo gpg --dearmor -o /usr/share/keyrings/perry.gpg
echo "deb [signed-by=/usr/share/keyrings/perry.gpg] https://perryts.github.io/perry-apt stable main" | sudo tee /etc/apt/sources.list.d/perry.list
sudo apt update && sudo apt install perry

From Source

git clone https://github.com/PerryTS/perry.git
cd perry
cargo build --release

The binary is at target/release/perry. Add it to your PATH:

# Add to ~/.zshrc or ~/.bashrc
export PATH="/path/to/perry/target/release:$PATH"

Self-Update

Once installed, Perry can update itself:

perry update

This downloads the latest release and atomically replaces the binary.

Verify Installation

perry doctor

This checks your installation, shows the current version, and reports if an update is available.

perry --version

Platform-Specific Setup

macOS

No additional setup needed. Perry uses the system cc linker and AppKit for UI apps.

For iOS development, install Xcode (not just Command Line Tools) for the iOS SDK and simulator.

Linux

Install GTK4 development libraries for UI apps:

# Ubuntu/Debian
sudo apt install libgtk-4-dev

# Fedora
sudo dnf install gtk4-devel

Windows

Two toolchain options — pick one. Both produce identical binaries.

Lightweight (recommended, ~1.5 GB, no Visual Studio):

winget install LLVM.LLVM
perry setup windows

perry setup windows downloads the Microsoft CRT + Windows SDK libraries via xwin after prompting for license acceptance. Pass --accept-license to skip the prompt in CI.

MSVC Build Tools (~8 GB):

Install Visual Studio Build Tools with the “Desktop development with C++” workload — via the Visual Studio Installer, or:

winget install Microsoft.VisualStudio.2022.BuildTools --override `
  "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

Run perry doctor to verify the toolchain. See the Windows platform guide for details.

What’s Next

• Write your first program
• Build a native app