How to install additional PHP extensions

We provide a number of PHP packages by default, but there will be times where you'll need to add additional PHP extensions in order to support a certain PHP library in your application. By default, we've included a popular tool called install-php-extensions that allows you to install almost any PHP module that you'll need.

Installing extensions is easy. All you need to do is find the extension you'd like to install on the docker-php-extension installer README. Once you have the name of the extensions, you'll need to add it to the Dockerfile in your project.

Example: Installing the "intl" extension

FROM serversideup/php:8.2.12-fpm-nginx-bookworm
RUN install-php-extensions intl

It's really that simple. The install-php-extensions tool will automatically install the operating system packages that are required for the PHP extension to work and add the extension to PHP.

For more details on this script, we encourage you to check out the GitHub repository for this project.

View the "docker-php-extension-installer" Project on GitHub →

Docker Compose

If you're using Docker Compose, you'll want to make sure that you're not calling our image directly with the image: key. Instead, you'll want to use the build: key and point to a Dockerfile in your project.

Original docker-compose.yml file

version: '3.7'
    image: serversideup/php:8.2.12-fpm-nginx-bookworm
      - .:/var/www/html/:cached

Updated docker-compose.yml

version: '3.7'
      context: .
      dockerfile: Dockerfile
      - .:/var/www/html/:cached

New File: Dockerfile

FROM serversideup/php:8.2.12-fpm-nginx-bookworm
RUN install-php-extensions imagick

Notice the options. We set a . to look for a dockerfile called Dockerfile within the same directory as our docker-compose.yml file. If your project is large, you may also want to include .dockerignore to ignore files that you do not want to include in your image.

For extra clarity, my project directory would look like this:

Project File Structure

├── Dockerfile
├── docker-compose.yml
└── public
    └── index.php

The Dockerfile is where all the magic will happen. This is where we pull the Server Side Up image as a dependency, then run standard shell commands to add the extension that we need.

The next time you run docker compose up, Docker will build and cache the image for you automatically.

You can verify the CLI option installed correctly by using php -i in CLI or phpinfo() in a PHP file.

⚠️ Important note about caching

  • You'll notice Docker likes to cache image builds (which is great for most functions)
  • If you make changes to your Dockerfile, you may need to include --build with your Docker compose command (read more here)

If you want to rebuild, then you would run this:

Rebuild on Docker Compose Initialization

docker compose up --build

Common PHP extensions that you might need

We compiled a list of extensions for you to reference.


intl is a PHP module that provides internationalization functions. You may want to install this module if you're using Laravel, specifically if you are validating emails with "DNS" or "spoof" validation.

Our tests showed this module will add about 40 MB of space to the Docker image, so we decided to not include it by default.

Learn more about the "intl" requirement for Laravel →

Don't see the extension you need?

If you're having trouble, open a discussion on GitHub →