static-php-cli/docs/en/guide/installation.md

Installation

Requirements

Platform	Architecture	Notes
Linux	x86_64, aarch64	Major distros supported (Alpine, Debian/Ubuntu, RHEL/CentOS, etc.)
macOS	x86_64 (Intel), arm64 (Apple Silicon)	macOS 12 or later
Windows	x86_64	Windows 10 Build 17063 or later

::: tip Both glibc-based distros (Debian, Ubuntu, Arch, etc.) and musl-based ones (Alpine) are supported on Linux. The doctor command will detect your environment and guide you through installing the right toolchain if needed. :::

Pick the installation method that fits your use case:

Method	Best for
Pre-built binary	Most users — download and run, no dependencies
From source	Contributors, or anyone who needs to modify core build logic
Vendor mode	Integrating StaticPHP into an existing PHP project

Pre-built binary

spc has no runtime dependencies — download the binary for your platform and it's ready to go.

Fun fact: spc itself is a static PHP binary built with StaticPHP. We use StaticPHP to build StaticPHP's own build tool.

# Linux x86_64
curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-linux-x86_64 -o spc
# Linux arm64
curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-linux-aarch64 -o spc
# macOS x86_64 (Intel)
curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-macos-x86_64 -o spc
# macOS arm64 (Apple Silicon)
curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-macos-aarch64 -o spc
# Windows x86_64 (PowerShell)
curl.exe -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-windows-x86_64.exe -o spc.exe

On Linux and macOS, mark the binary as executable before running it:

chmod +x spc && ./spc --version

From source

This is the right path if you want to contribute to StaticPHP, or need to modify the core registry and build scripts. You'll need PHP >= 8.4, Composer, and the mbstring,posix,pcntl,iconv,phar,zlib extensions.

git clone https://github.com/crazywhalecc/static-php-cli.git --branch v3
cd static-php-cli
composer install

If you don't have PHP or Composer installed, use the bundled setup script to install a self-contained runtime:

::: code-group

bin/setup-runtime

.\bin\setup-runtime.ps1
.\bin\setup-runtime.ps1 add-path   # add runtime/ to PATH

:::

The script downloads php and composer into a runtime/ subdirectory. You then have two options:

1. Call them directly (no PATH changes needed):

   runtime/php bin/spc --help
   runtime/php runtime/composer install
   

2. Add runtime/ to your PATH so you can use php, composer, and bin/spc without prefixes:

   export PATH="/path/to/static-php-cli/runtime:$PATH"
   # Add this to ~/.bashrc or ~/.zshrc to make it permanent
   

Vendor mode

If you already have a PHP project and want to call StaticPHP's build APIs directly, or use a custom registry to support private libraries and extensions, pull it in as a Composer dependency:

composer require crazywhalecc/static-php-cli

See the Extending StaticPHP guide for details.

Verify your build environment

Vendor mode users can skip this step.

Once installed, run doctor to check that your system has the required build tools (cmake, make, a C compiler, etc.):

# Using the spc binary
./spc doctor
# From source
bin/spc doctor

If anything is missing, --auto-fix will attempt to install it for you:

./spc doctor --auto-fix

Once doctor reports everything is good, head over to First Build.