How to compile PHP from source on Debian/Ubuntu - Beginner's guide
Compiling PHP from its source is easier than it sounds. This is a more beginner-friendly guide on how to fetch its source from GitHub, install the necessaries for compilation, compile, and test run PHP.
PHP is readily available to download and install for many operating systems, including Windows, Debian/Ubuntu, Fedora, Mac OS, etc. Installing from such sources does not require compiling PHP, because they are already compiled, and ready to install. Further, they often contain various PHP extensions as decoupled install-able packages, so it is easy to customize the PHP run time with any combination of PHP extensions.
This guide focuses on compiling PHP from its source code, so it's easy to try out new features not yet released. The compiled form will be suitable for testing, rather than using them in a production server.
Looking for a TL;DR?
A short version of the guide for the copy-paste pleasure is available at the TL;DR section.
The initial setup of installing the build tools (such as compilers and libraries) will take about five minutes. On a fresh Ubuntu 21.04 installation, it will require downloading ~210 MB of files. This is a one-time setup.
The Git repository of PHP in
masterbranch (the branch for the latest and upcoming version) is around 420 MB at the time of writing. Once the Git repository is cloned, new changes can be pulled without having to download the whole repository over and over again.
Building the configuration script and configuring the build will take about a minute. This process is mostly checking if all required dependencies are present in the system.
Compiling PHP can take anywhere from 2 minutes to 15-20 minutes, depending on the CPU core/thread count and the speed. On an 8-core 16 thread CPU at 2.9 GHz, it usually takes 2 minutes to complete. On the same CPU only utilizing just one CPU core, it takes ~16 minutes to compile.
This guide is about compiling PHP from its source, on Debian 9 (Stretch) or later or Ubuntu 18.04 (Bionic Beaver) or later. This was tested to work on Debian versions up to 10 (Buster) and Ubuntu versions up to 21.04 (Hirsute Hippo).
Using Fedora/RHEL/CentOS ?
See How to compile PHP from source on Fedora/RHEL/etc.
For the PHP source and build tools, a network connection capable to download ~ 600 MB will be necessary for the first run. Each subsequent build will be merely downloading the new commits from GitHub, and will be in the range of just few kilobytes to a megabyte or two. Make sure a disk space of at least 1 GB left.
The PHP source code is version-controlled using Git, and it is available to download over HTTP as a zip archive, or preferably using Git. The source code is available on GitHub, which is now the canonical source.
Optional: A virtual machine/container
Compiling PHP and testing it out on a virtual machine makes everything so much easier and cleaner. If possible, make sure to follow the rest of the guide on a virtual machine or a container.
- For Windows users, a WSL2 running Ubuntu will be the most straight-forward approach.
- A virtual machine running Ubuntu/Debian, using Virtual Box, available on several operating systems including Windows and Mac OS.
- Running on Ubuntu docker image.
Optional: GitHub account with SSH Access
It is possible to download the PHP source from the Git repository hosted on GitHub. It allows downloading the source code without any authentication.
To contribute to the PHP project, it requires a GitHub account to fork and make pull requests. It is a simple and one-off step to register and authenticate yourself to GitHub over SSH, and the process is documented at GitHub documentation.
2. Install Build Tools
All the basic tools to compile a minimal version of PHP can be installed in a single-go.
All commands that start with
sudo might require occasional password confirmation.
sudo apt install build-essential autoconf libtool bison re2c pkg-config
Depending on the existing software available on the system, it can download anywhere from 0 to ~220 MB.
build-essentialincludes tools like
gcc, the GNU C compiler, and
make, a utility to direct the compilation scripts.
autoconfis used to generate the
configurescript that is used later in the compilation.
libtoolis a tool that helps to manage and locate shared libraries.
bisonis YACC-compatible parser generator
re2cis a tool that is used to generate the PHP's lexer.
Note that these are the absolute minimum list of tools. Additional PHP extensions require additional dependencies, that are explained later in this guide under each extension.
3. Git Clone PHP Source
With the build tooling installed, it is now time to download the PHP source code from the Git repository.
The PHP source is available in the Git repository hosted at github.com/php/php-src.
git clone https://github.com/php/php-src.git --branch=master
If SSH is configured with GitHub, it is possible and to clone over SSH as well:
git clone email@example.com:php/php-src.git --branch=master
--branch=master option for Git narrows the clone operation to the
master branch. This can slightly reduce the download size, as it skips commits that does not belong to other branches.
A shallow clone can dramatically reduce the download size and clone time by not including any of the historical commits. This is ideal for a one-off test, but a shallow-clone does not allow making additional commits because the commit history is not available. To make a shallow clone, use the
git clone https://github.com/php/php-src.git --depth=1
Once it is finished,
cd to the
php-src directory that contains the PHP source:
PHP source repository includes a script that generates a new
5. Configure the build
./configure script contains dozens of option to customize the PHP build.
./configure --help shows the entire list of options available to use.
The flags shown in the
./configure --help follow a pattern of
--with-XYZ. It accepts multiple flags, and is often a very long one in most PHP setups primed for production use.
./configure --enable-ftp --with-openssl --disable-cgi
If the flag is passed, the extension/SAPI with name
XXX will be enabled. Using
--enable-XXX=shared pattern makes the extension to be compiled to a separate file so it can be enabled/disabled from the PHP INI files.
For example, running
./configure --enable-ftp enables the FTP extension. running
./configure --enable-ftp=shared enables the extension to be compiled as a shared extension; the extension will be compiled to a separate
.so file (
.dll in Windows), so it can be enabled/disabled using a PHP configuration file.
Not all extensions support compiling to a shared extension.
In addition to extensions, the
--enable-XYZ options are available for Server APIs (SAPIs) and specific features as well. Notably, the
--enable-zts enables thread-safety feature in the build.
This option is similar to
--enable-XYZ pattern that they enable various PHP extensions and features. Note these extensions/features often require additional dependencies.
For example, the OpenSSL extension, enabled with
./configure --with-openssl depends on the development files of the OpenSSL library. In Ubuntu/Debian systems, they can be easily installed with the
libssl-dev package. The
-dev suffix to the package name indicates that it is a development package. To fulfill the requirements for OpenSSL extension, install
sudo apt install libssl-dev
Appendix: Extension Dependencies
An up-to-date list of extension requirements are listed in Appendix: Extension Dependencies section of this guide.
The opposite of
--enable-XYZ flags. The presence of this flag means PHP is configured to include that extension/feature/SAPI by default, unless the
--disable-XYZ option is passed.
--disable-all flag disables all extensions, which allows a clean slate for individual extensions to be enabled with
By default, PHP compiles with SQLite support built-in. Disabling the SQLite3 extensions makes it possible to compile PHP without having to install SQLite3 dependencies.
./configure --without-sqlite3 --without-pdo-sqlite
./configure command is cumbersome. When the
./configure script is run, it saves the command to a
./config.nice file, that executes the exact same command as before, plus append additional options.
After the first
./configure run has completed, using the
./config.nice file helps to avoid typing the same
./configure options again and again.
./config.nice script has completed, it is now time to run the compiler.
Depending on the CPU cores and threads available, this can take anywhere in the range from 2 minutes to 15-20 minutes.
make -j $(nproc)
make command is used to run the compilation using the C compiler. It accepts a
-j parameter, that can be used to configure parallel processing. Output of the
nproc command, which returns the number of available CPU threads in the system is then set for the
make -j parameter.
-j option is not present, it will use a single CPU thread by default. To set a specific number of threads, simply specify the number for the
7. Install/try it out
The compiled binaries will be available in the
./sapi directory. To immediately run the PHP CLI, for example, call the
PHP's interactive CLI is opened using the
Alternately, the compiled PHP version can be installed on the system, so other tools can easily use the
php binary in PATH.
sudo make install
Appendix: Extension Dependencies
Following are command-line arguments passed to the
./configure script to enable/disable/configure PHP extensions and features.
The following extensions are PHP core extensions, and cannot be disabled. Older PHP versions might have had a flag to toggle this extension, but they are not valid anymore for these extensions.
|Hash||Core extension since PHP 7.4|
|JSON||Core extension since PHP 8.0|
|SPL||Core extension since PHP 5.3|
Enabled by default
The following extensions are enabled by default, but can be disabled if necessary. The
--disable-all flag also disables all of them.
Disabled by default
Compiling additional extensions often require its dependencies in place. Here is a list of PHP extensions and their dependencies, and the
./configure flag to enable it.
The Dependencies column lists the package names in Ubuntu/Debian repositories. Install them using the package manager:
sudo apt install <package-name>
- GD extensions Avif image support (
libavif-dev) is only supported on PHP 8.1 and later.
The entire list of commands above are shortened below:
sudo apt install build-essential autoconf libtool bison re2c git clone https://github.com/php/php-src.git --branch=master cd php-src ./buildconf ./configure make -j $(nproc) sudo make install
cd php-src git pull --rebase ./buildconf --force ./config.nice make -j $(nproc) sudo make install
./config.nice is also available.