How to Build a Fully Static PHP Binary with static-php-cli on Linux and macOS

Introduction

static-php-cli is a tool for creating statically compiled PHP binaries that run on Linux and macOS. It supports PHP 7.4 through 8.3 and can produce a single executable that includes the PHP runtime and selected extensions.

Supported Build Environments

The tool indicates support with symbols: ⚙️ for GitHub Action builds, 💻 for local builds, and an empty cell for unsupported configurations. The matrix shows:

macOS x86_64 and aarch64 – both symbols.

Linux x86_64 and aarch64 – both symbols.

Windows x86_64 – both symbols (no aarch64 support).

FreeBSD x86_64 and aarch64 – only local build support.

Linux builds have been tested on Ubuntu, Debian, and Alpine; other distributions may require Docker to avoid environment issues. macOS binaries for one architecture cannot run on the other, and Rosetta 2 does not guarantee compatibility.

Windows currently supports only the x86_64 architecture; 32‑bit x86 and arm64 are not supported.

Supported PHP Versions

static-php-cli works with PHP 7.4 – 8.3. Earlier versions are theoretically possible but not officially supported because many extensions have dropped compatibility. Using the newest PHP version is recommended for the best experience.

Local Build Process

Manual Binary Download

You can download a pre‑built spc binary for Linux or macOS:

curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64

Make it executable: chmod +x ./spc Check the version:

./spc --version
static-php-cli 2.3.2

Downloading Source Dependencies

Run the download command to fetch php-src and all required libraries:

./spc download --for-extensions=pcntl,zstd --with-php=8.2

Environment Check

If the spc command runs but the build fails, execute the doctor tool to verify required system packages: ./spc doctor Typical output confirms the presence of tools, headers, and a sufficient CMake version (≥ 3.18). If CMake is too old, upgrade manually:

wget https://cmake.org/files/v3.22/cmake-3.22.5.tar.gz
 tar -zxvf cmake-3.22.5.tar.gz
 cd cmake-3.22.5
 ./configure
 make
 sudo make install

Building PHP

Before building, ensure dependencies are downloaded and the environment passes the doctor check. Then run:

./spc build pcntl,zstd --build-cli

Build Result

_        _   _                 _
___| |_ __ _| |_(_) ___      _ __| |__  _ __
/ __| __/ _` | __| |/ __|____| '_ \| '_ \| '_ \
\__ \ || (_| | |_| | (_|_____| |_) | | | | |_) |
|___/\__\__,_|\__|_|\___|    .__/|_| |_|.__/   v2.3.2
[INFO] Build OS: Linux (x86_64)
[INFO] Build SAPI: cli
[INFO] Extensions (2): pcntl,zstd
[INFO] Libraries (1): zstd
[INFO] PHP Version: 8.2.22
... (build log continues) ...
[INFO] Build complete, used 554.717 s !
[INFO] Static php binary path: /home/www/build/buildroot/bin/php

Using the Built PHP CLI

The resulting binary is placed in buildroot/bin/php. You can inspect it:

tree -L 1 buildroot/bin
# output shows php, pkg-config, zstd utilities, etc.

./php -v
PHP 8.2.22 (cli) (built: Aug  9 2024 23:01:57) (NTS)

./php -m
[PHP Modules]
Core
date
hash
json
pcntl
pcre
random
Reflection
SPL
standard
zstd

Package the binary for distribution:

tar -czvf php-8.2.22-static-bin-x86_64.tar.gz /home/www/build/buildroot/bin/php

Advanced Usage

Rebuilding or Debugging

To start a fresh build, delete the buildroot/ and source/ directories, then run the desired build command again:

# remove previous artifacts
rm -rf buildroot source
# rebuild with selected extensions
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli

Building Multiple PHP Versions

Use the switch-php-version helper to change the target PHP version without re‑downloading all libraries:

# switch to 8.3
bin/spc switch-php-version 8.3
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
# switch to 7.4
bin/spc switch-php-version 7.4
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli

After switching, you can verify the version:

/home/www/build/buildroot/bin/php -v
PHP 7.4.33 (cli) (built: Aug 10 2024 09:30:26) (NTS)