Easy installation of PHP extensions in official PHP Docker images

This repository contains a script that can be used to easily install a PHP extension inside the official PHP Docker images.

The script will install all the required APT/APK packages; at the end of the script execution, the no-more needed packages will be removed so that the image will be much smaller.

Supported docker images are:

• Debian-based docker images: since jessie (Debian 8) (minimum PHP version: 5.5)
• Alpine-based docker images: since Alpine 3.9 (minimum PHP version: 7.1)

See also the notes in the Special requirements section.

Usage

You have many ways to use this script within your Dockerfiles.

Here's a list of sample Dockerfiles that install the GD and xdebug PHP extensions:

Downloading the script on the fly with ADD

FROM php:7.2-cli

ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/

RUN chmod +x /usr/local/bin/install-php-extensions && \
    install-php-extensions gd xdebug

Downloading the script on the fly with curl

FROM php:7.2-cli

RUN curl -sSLf \
        -o /usr/local/bin/install-php-extensions \
        https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions && \
    chmod +x /usr/local/bin/install-php-extensions && \
    install-php-extensions gd xdebug

Direct execution with curl

FROM php:8.2-cli

RUN curl -sSL https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions -o - | sh -s \
      gd xdebug

Copying the script from a Docker image

FROM php:7.2-cli

COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/

RUN install-php-extensions gd xdebug

Warning: by using this method you may use an outdated version of the mlocati/php-extension-installer image. You may want to run docker pull mlocati/php-extension-installer in order to use an up-to-date version.

Using the script of a Docker image

RUN  --mount=type=bind,from=mlocati/php-extension-installer:latest,source=/usr/bin/install-php-extensions,target=/usr/local/bin/install-php-extensions \
      install-php-extensions gd xdebug

Warning: by using this method you may use an outdated version of the mlocati/php-extension-installer image. You may want to run docker pull mlocati/php-extension-installer in order to use an up-to-date version.

Installing specific versions of an extension

Simply append -<version> to the module name. For example:

install-php-extensions xdebug-2.9.7

The script also supports resolving compatible versions by prefixing the version with a caret (^). For example:

# Install the most recent xdebug 2.x version (for example 2.9.8)
install-php-extensions xdebug-^2
# Install the most recent xdebug 2.8.x version (for example 2.8.1)
install-php-extensions xdebug-^2.8

Please remark that with the syntax above you'll get the vary latest compatible version, which may be unstable. In order to install the most recent stable version, you can append @stable:

# Install the most recent STABLE xdebug 3.x version (for example 3.2.2)
install-php-extensions xdebug-^3@stable

(valid suffixes are: @snapshot, @devel, @alpha, @beta, and @stable)

Pre-release versions extensions available on PECL can be setup by suffixing the extension's name with its state i.e. alpha, beta, rc, preview, devel or snapshot. For example:

install-php-extensions xdebug-beta

TIP: When the latest version available on PECL is not stable, and you want to keep the last stable version, force it by suffixing the extension's name with the stable state. For example:

install-php-extensions mongodb-stable

Installing an extension from its source code

You can also install PHP extensions from source code (provided that it comes with a package.xml or a package2.xml file).

Accepted formats are:

• A short version for repositories hosted on GitHub.
  For example, for the php-memcached-dev/php-memcached GitHub repository, you can simply write:

  # Install from a specific commit (full commit SHA-1)
  install-php-extensions php-memcached-dev/php-memcached@8f106564e6bb005ca6100b12ccc89000daafa9d8
  # Install from a specific commit (short commit SHA-1)
  install-php-extensions php-memcached-dev/php-memcached@8f106564e6bb
  # Install from tag v3.2.0RC2
  install-php-extensions php-memcached-dev/php-memcached@v3.2.0RC2
  install-php-extensions php-memcached-dev/php-memcached@refs/tags/v3.2.0RC2
  # Install from branch master
  install-php-extensions php-memcached-dev/php-memcached@master
  install-php-extensions php-memcached-dev/php-memcached@refs/heads/master
  

• An URL providing an archive containing the source code.
  Examples:

  # tgz archive for commit 8f106564e6bb005ca6100b12ccc89000daafa9d8
  install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/8f106564e6bb005ca6100b12ccc89000daafa9d8
  # tgz archive for tag v3.1.5
  install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/tags/v3.1.5
  # tgz archive for branch master
  install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/heads/master
  

• The absolute path of a local directory.
  Examples:

  # Download the source code
  curl -o /tmp/source.tgz https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/tags/v3.1.5
  tar xzf /tmp/source.tgz -C /tmp
  install-php-extensions /tmp/php-memcached-3.1.5
  
  

Installing composer

You can also install composer, and you also can specify a major version of it, or a full version.

Examples:

# Install the latest version
install-php-extensions @composer
# Install the latest 1.x version
install-php-extensions @composer-1
# Install a specific version
install-php-extensions @composer-2.0.2

Issue with Let's Encrypt certificates

The root CA certificate of Let's Encrypt changes (more details here).
That breaks old linux distributions, namely:

• Debian Jessie (8)
• Debian Stretch (9)
• Alpine Linux 3.7
• Alpine Linux 3.8

This script can fix this issue: simply pass @fix_letsencrypt as an argument:

install-php-extensions @fix_letsencrypt

Supported PHP extensions

Extension	PHP 5.5	PHP 5.6	PHP 7.0	PHP 7.1	PHP 7.2	PHP 7.3	PHP 7.4	PHP 8.0	PHP 8.1	PHP 8.2	PHP 8.3
amqp	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
apcu	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
apcu_bc			✓	✓	✓	✓	✓
ast			✓	✓	✓	✓	✓	✓	✓	✓	✓
bcmath	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
bitset	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
blackfire	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
bz2	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
calendar	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
cassandra*					✓	✓	✓	✓	✓	✓	✓
cmark			✓	✓	✓	✓	✓
csv						✓	✓	✓	✓	✓	✓
dba	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
ddtrace*		✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
decimal			✓	✓	✓	✓	✓	✓	✓	✓	✓
ds			✓	✓	✓	✓	✓	✓	✓	✓	✓
ecma_intl*										✓	✓
enchant	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
ev	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
event	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
excimer				✓	✓	✓	✓	✓	✓	✓	✓
exif	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
ffi							✓	✓	✓	✓	✓
ftp										✓	✓
gd	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
gearman	✓	✓	✓	✓	✓	✓	✓	✓
geoip	✓	✓	✓	✓	✓	✓	✓
geos*	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
geospatial	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
gettext	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
gmagick	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
gmp	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
gnupg	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
grpc	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
http	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
igbinary	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
imagick	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
imap	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
inotify	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
interbase	✓	✓	✓	✓	✓	✓
intl	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
ion									✓	✓	✓
ioncube_loader	✓	✓	✓	✓	✓	✓	✓		✓	✓
jsmin	✓	✓	✓	✓	✓	✓	✓
json_post	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
jsonpath							✓	✓	✓	✓	✓
ldap	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
luasandbox	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
lz4*		✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
lzf	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
mailparse	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
maxminddb					✓	✓	✓	✓	✓	✓	✓
mcrypt	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
memcache	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
memcached	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
memprof*	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
mongo	✓	✓
mongodb	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
mosquitto	✓	✓	✓	✓	✓	✓	✓
msgpack	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
mssql	✓	✓
mysql	✓	✓
mysqli	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
oauth	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
oci8	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
odbc	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
opcache	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
opencensus			✓	✓	✓	✓	✓	✓	✓	✓	✓
openswoole					✓	✓	✓	✓	✓	✓	✓
opentelemetry								✓	✓	✓	✓
parallel*				✓	✓	✓	✓	✓	✓	✓	✓
parle*			✓	✓	✓	✓	✓	✓	✓	✓	✓
pcntl	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
pcov			✓	✓	✓	✓	✓	✓	✓	✓	✓
pdo_dblib	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
pdo_firebird	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
pdo_mysql	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
pdo_oci			✓	✓	✓	✓	✓	✓	✓	✓	✓
pdo_odbc	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
pdo_pgsql	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
pdo_sqlsrv*			✓	✓	✓	✓	✓	✓	✓	✓	✓
pgsql	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
php_trie						✓	✓	✓	✓	✓	✓
pkcs11							✓	✓	✓	✓	✓
pq			✓	✓	✓	✓	✓	✓	✓	✓	✓
propro	✓	✓	✓	✓	✓	✓	✓
protobuf	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
pspell	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
pthreads*	✓	✓	✓
raphf	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
rdkafka	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
recode	✓	✓	✓	✓	✓	✓
redis	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
relay							✓	✓	✓	✓	✓
seasclick	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
seaslog	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
shmop	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
simdjson*				✓	✓	✓	✓	✓	✓	✓	✓
smbclient	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
snappy	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
snmp	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
snuffleupagus			✓	✓	✓	✓	✓	✓	✓	✓	✓
soap	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
sockets	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
sodium*		✓	✓	✓
solr	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
sourceguardian	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
spx	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
sqlsrv*			✓	✓	✓	✓	✓	✓	✓	✓	✓
ssh2	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
stomp	✓	✓	✓	✓	✓	✓	✓			✓	✓
swoole	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
sybase_ct	✓	✓
sync	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
sysvmsg	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
sysvsem	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
sysvshm	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
tensor					✓	✓	✓	✓	✓	✓
tideways	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
tidy	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
timezonedb	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
uopz	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
uploadprogress	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
uuid	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
uv								✓	✓	✓	✓
vips*			✓	✓	✓	✓	✓	✓	✓	✓	✓
vld	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
wddx	✓	✓	✓	✓	✓	✓
xdebug	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
xdiff	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
xhprof	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
xlswriter			✓	✓	✓	✓	✓	✓	✓	✓	✓
xmldiff	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
xmlrpc	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
xsl	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
yac			✓	✓	✓	✓	✓	✓	✓	✓	✓
yaml	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
yar	✓	✓	✓	✓	✓	✓	✓	✓	✓
zephir_parser			✓	✓	✓	✓	✓	✓	✓	✓	✓
zip	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
zmq	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
zookeeper	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
zstd	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓

Number of supported extensions: 143

PS: the pre-installed PHP extensions are excluded from this list. You can list them with the following command (change php:7.2-cli to reflect the PHP version you are interested in):

$ docker run --rm php:7.2-cli php -m
[PHP Modules]
Core
ctype
curl
date
dom
fileinfo
filter
ftp
hash
iconv
json
libxml
mbstring
mysqlnd
openssl
pcre
PDO
pdo_sqlite
Phar
posix
readline
Reflection
session
SimpleXML
sodium
SPL
sqlite3
standard
tokenizer
xml
xmlreader
xmlwriter
zlib

[Zend Modules]

Configuration

You can configure the behavior of the script, as well as fine-tune some extensions in order fit your needs, by using environment variables.

Here's an example:

IPE_LZF_BETTERCOMPRESSION=1 install-php-extensions lzf

Here's the list of all the supported environment variables:

Extension	Environment variable	Description
	IPE_DEBUG=1	By setting this environment variable, the script will print all the commands it executes (it will be very verbose, useful only for debug purposes)
	IPE_PROCESSOR_COUNT	Set this environment variable to override the number of processors detected by the script (used for parallel compilation)
	IPE_DONT_ENABLE=1	By default the script will install and enable the extensions. If you want to only install them (without enabling them) you can set this environment variable. To enable the extensions at a later time you can execute the command docker-php-ext-enable-<extension> (for example: docker-php-ext-enable-xdebug). Beware: installing some PHP extensions require that other PHP extensions are already enabled, so use this feature wisely.
	IPE_KEEP_SYSPKG_CACHE=1	By default the script will clear the apt/apk/pear cache in order to save disk space. You can disable it by setting this environment variable
lzf	IPE_LZF_BETTERCOMPRESSION=1	By default install-php-extensions compiles the lzf extension to prefer speed over size; you can use this environment variable to compile it preferring size over speed
event	IPE_EVENT_NAMESPACE=...	By default the event classes are defined in the root namespace. You can use this environment variable to specify a custom namespace
gd	IPE_GD_WITHOUTAVIF=1	Since PHP 8.1, gd supports the AVIF format. Enabling it requires compiling libaom/libdav1d/libyuv/libavif on Debian 11- and Alpine 3.14-, which is time-consuming. You can disable AVIF support by setting this environment variable on Debian 11- and Alpine 3.14-
oci8 & pdo_oci	IPE_INSTANTCLIENT_BASIC=1	The oci8 and pdo_oci PHP extensions require Oracle Instant Client. In order to save disk space, we install the Basic Lite version: if you want to install the Basic (non-lite) version simply set this environment variable
http, intl, mongodb	IPE_ICU_EN_ONLY=1	Some extensions require the ICU library, use this flag to install a smaller, but English-only, ICU library on Alpine 3.16 and later
pspell	IPE_ASPELL_LANGUAGES='...'	Configure the languages to be made available (for example: IPE_ASPELL_LANGUAGES='en fr'). If omitted, we'll assume en
	IPE_DEB_ARCHIVE & IPE_DEB_ARCHIVE_SECURITY	The APT packages of very old Debian versions (eg Jessie) may have been archived: you can use these environment variables to specify custom URLs of these APT archives

Special requirements

Some extensions have special requirements:

Extension	Requirements
cassandra	• Not available in jessie docker images • Not available in stretch docker images • Not available in buster docker images • Not available in bullseye docker images • Not available in bookworm docker images
ddtrace	Not available in jessie docker images
ecma_intl	• Not available in buster docker images • Not available in bullseye docker images
geos	• Not available in alpine3.9 docker images • Not available in alpine3.10 docker images
lz4	Not available in jessie docker images
memprof	• Not available in alpine3.9 docker images • Not available in alpine3.10 docker images • Not available in alpine3.11 docker images • Not available in alpine3.12 docker images • Not available in alpine3.13 docker images • Not available in alpine3.14 docker images • Not available in alpine3.15 docker images
parallel	Requires images with PHP compiled with thread-safety enabled (zts)
parle	Not available in jessie docker images
pdo_sqlsrv	Not available in ARM architectures
pthreads	Requires images with PHP compiled with thread-safety enabled (zts)
simdjson	• Not available in jessie docker images • Not available in stretch docker images
sodium	Not available in jessie docker images
sqlsrv	• Not available in 7.1-alpine3.9 docker images • Not available in 7.1-alpine3.10 docker images • Not available in ARM architectures
vips	• Not available in alpine3.9 docker images • Not available in jessie docker images

How do I know which Linux distribution I am using?

You can run this command:

cat /etc/os-release

For example:

• for Debian 11 (Bullseye) you'll see:

  PRETTY_NAME="Debian GNU/Linux 11 (bullseye)"
  

• for Alpine Linux 3.14 you'll see:

  PRETTY_NAME="Alpine Linux v3.14"
  

Tests

When submitting a pull request, a GitHub Action is executed to check if affected PHP extensions actually work (see below).

Furthermore, we also check that new versions of extensions in the PECL repository will still work. This is done on a scheduled basis with another GitHub Action.
In case of failure, a message is sent to a Telegram Channel.
Feel free to subscribe to it to receive failure notifications.

How to contribute

Formatting code

Before submitting any pull request, you should execute the lint script in the scripts directory (or lint.bat on Windows).

If you don't do that, and if there's a coding style error, you'll see that the Check shell coding style and/or the Check PHP coding style GitHub Actions will fail.

The error will be something like this:

--- filename.orig
+++ filename
@@ -line number,7 +line number,7 @@
     good line of code #1
     good line of code #2
     good line of code #3
-    the original line with a wrong coding style
+    the line wrong coding style that has been corrected
     good line of code #4
     good line of code #5
     good line of code #6

So, you should fix highlighted line (the one(s) at line number) by replacing what you see after the - with what you see after the +

Adding support to a new PHP extension?

1. change the install-php-extensions script
2. update the data/supported-extensions file, adding a new line with the handle of the extension and the list of supported PHP versions
3. if the extension requires ZTS images:
   add a new line to the data/special-requirements file, with the extension handle followed by a space and zts

See this pull request for an example.

Changing the supported PHP versions for an already supported PHP extension?

1. change the install-php-extensions script
2. update the data/supported-extensions file, adding the new PHP version to the existing line corresponding to the updated extension

See this pull request for an example.

Improving code for an already supported extension?

If you change some code that affects one or more extensions, please add a line with Test: extension1, extension2 to the message of one of the pull request commits. That way, the test jobs will check the extension even if you don't touch the data/supported-extensions file.

Here's an example of a commit message:

Improve the GD and ZIP extensions

Test: gd, zip

Tests only check the installation of a single PHP extension at a time. If you want to test installing more PHP extensions at the same time, use a commit message like this:

Improve the GD and ZIP extensions

Test: gd+zip

If your pull request contains multiple commits, we'll check the "Test:" message of every commit. If you want to stop parsing next commits, add -STOP- in the "Test:" line, for example:

Improve the GD and ZIP extensions

Test: gd, zip, -STOP-

See this pull request for an example.

PHP requirements and configure options

PHP extensions published on the PECL archive contain a package.xml (or package2.xml) file describing the supported PHP versions and the options that can be used to compile it. When we add support for a new PHP extension, and when a new version of a PHP extension is released, we have to check those constraints.

It's a rather tedious task, so I developed a project that lets you easily check those constraints: you can find it at https://mlocati.github.io/pecl-info (here you can find its source code).

For the maintainers

See the MAINTAINERS.md file.

Do you want to really say thank you?

You can offer me a monthly coffee or a one-time coffee 😉