Driver FixRecommendedSound, Wi-Fi or graphics acting up? Check drivers firstFind missing or outdated drivers fast.Check DriversHalloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsClean PCRecommendedOne scan can reveal what keeps slowing WindowsLook for cleanup and repair opportunities.Run Scan×
FREEDOM251

Freedom251 › Blog › Docker

How to Use docker-php-ext-install in a PHP Dockerfile

By Freedom251 Team · · 8 min read

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use docker-php-ext-install to compile PHP core extensions that are available in the official PHP image. Start from a matching cli, apache or fpm image, check whether the module already exists with php -m, install the extension’s operating-system development libraries, configure optional features when required, and then run the helper script. For example:

FROM php:8.2-apache
RUN docker-php-ext-install pdo pdo_mysql

The command does not replace dependency installation, and it is not the right installer for every PHP extension. Core extensions use docker-php-ext-install; PECL extensions normally use pecl install followed by docker-php-ext-enable.

As an Amazon Associate I earn from qualifying purchases.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

What docker-php-ext-install does

docker-php-ext-install is a helper script shipped with the official PHP Docker images. It builds extensions from the PHP source bundled with the selected image and installs them into that image. The same image family provides docker-php-ext-configure for custom configure arguments and docker-php-ext-enable for enabling installed shared modules.

These scripts are part of the image, not general Docker commands. They are available when you use an official PHP image tag such as php:8.2-cli, php:8.2-apache or php:8.2-fpm. The tag determines the PHP version, the base distribution and which extensions and build tools are available.

#1 Best Overall
Sale
TOZO A1 Wireless Earbuds Bluetooth 5.3 Light Weight in Ear Headphones | IPX5 Waterproof,2 Mics for AI Calls,Immersive Premium Sound Bass Headset with Charging Case,32 EQ via App Black
  • [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
  • [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
  • [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
  • [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
  • [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.

Choose the image and verify the module first

1. Match the runtime image

Choose the variant that will actually run your application:

  • cli is intended for command-line scripts and workers.
  • apache bundles PHP with Apache for applications served by that web server.
  • fpm provides PHP-FPM for use behind a separate web server or proxy.

Keep the PHP tag consistent with your application and deployment environment. Package names, available extensions and configure flags vary between PHP tags and between Debian-based and Alpine-based images.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

2. Check what is already compiled in

Many extensions are already present in an official image. Check before adding a build step:

docker run --rm php:8.2-cli php -m
docker run --rm php:8.2-cli php -i

For a local Dockerfile, you can also add RUN php -m temporarily and inspect the build output. If the requested module is already listed, compiling it again wastes build time and can create avoidable dependency layers.

The core installation workflow

For an extension that is part of the PHP source shipped in the image, use this sequence:

  1. Start with the correct official PHP tag. The operating-system family matters because Debian images use apt-get, while Alpine images use apk.
  2. Confirm the extension is absent. Use php -m or php -i in the image.
  3. Install development libraries and headers. The helper script does not fetch system dependencies for you. Install every library required by the extension before compiling.
  4. Configure optional features when needed. Run docker-php-ext-configure with the extension-specific flags before installation.
  5. Compile and install. Run docker-php-ext-install, adding parallel jobs when the builder has enough CPU and memory.
  6. Clean the build layer. Remove package indexes in the same layer as the package installation, and avoid leaving build-only files in the runtime image.

Installing operating-system dependencies

PHP extensions often wrap native libraries. Headers and development packages must be installed before the helper script runs. The exact names depend on the selected PHP tag and base distribution, so copy an example only after checking that it matches your image.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #2
Sale
Smart Watch for Men Women Compatible with iPhone Samsung Android Phone 1.69 inch Full Touch Screen IP68 Waterproof Bluetooh Fitness Tracker Heart Rate/Sleep Monitor (Black)
  • 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
  • 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
  • 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
  • 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
  • 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.

Debian-based images

On Debian-based official images, install packages with apt-get. Keep the update, installation and package-index cleanup in one RUN instruction so an intermediate layer does not retain stale indexes:

RUN apt-get update 
    && apt-get install -y --no-install-recommends 
        <development-package> 
    && rm -rf /var/lib/apt/lists/* 
    && docker-php-ext-install <extension>

Replace the placeholders with packages required by the particular extension and PHP image. The cleanup removes the downloaded package lists; it does not remove the libraries needed by the compiled module.

Alpine-based images

Alpine images use apk rather than apt-get. Select Alpine development packages that correspond to the extension and the Alpine release in your PHP tag. Do not paste Debian package names into an Alpine build: the names and sometimes the available library versions differ. The helper scripts still perform the PHP-side configure and compile steps, but dependency installation remains your responsibility.

Configure, install and enable are different operations

Helper Use it for Typical position
docker-php-ext-configure Passing non-default configure arguments to a core extension After system libraries are installed and before compilation
docker-php-ext-install Compiling extensions available in the PHP source bundled with the image After dependency installation and optional configuration
docker-php-ext-enable Enabling an installed shared module, including a module installed through PECL After the module has been installed

Running docker-php-ext-enable does not compile a missing extension. Conversely, installing a module does not mean you should blindly enable it if the image already enables it or if it is built statically.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Example: PDO and MySQL support

When the required PDO drivers are available in the image source, a minimal Apache image can install them together:

FROM php:8.2-apache
RUN docker-php-ext-install pdo pdo_mysql

pdo supplies the database abstraction layer and pdo_mysql supplies the MySQL driver. Verify the result in the built image:

Rank #3
New Bee Guitar Cable 10ft Electric Instrument Bass AMP Cord
  • [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
  • [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
  • [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
  • [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
  • [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by
docker build -t php-app .
docker run --rm php-app php -m

Look for both module names in the output. If compilation fails before either appears, inspect the first missing-header or configure error rather than adding unrelated packages.

Example: GD with FreeType and JPEG

The GD extension illustrates why configuration and system libraries are separate steps. The documented PHP 8.2 FPM pattern installs the FreeType, JPEG and PNG development libraries, configures GD with FreeType and JPEG support, and compiles it with all available processor cores:

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
FROM php:8.2-fpm
RUN apt-get update && apt-get install -y 
        libfreetype-dev 
        libjpeg62-turbo-dev 
        libpng-dev 
    && rm -rf /var/lib/apt/lists/* 
    && docker-php-ext-configure gd --with-freetype --with-jpeg 
    && docker-php-ext-install -j$(nproc) gd

Here, the Debian packages provide native headers and libraries; docker-php-ext-configure gd requests the optional FreeType and JPEG features; and -j$(nproc) allows parallel compilation. Use the flags and package names appropriate to your selected PHP tag. A flag accepted by one PHP version may change in another.

When PECL is the correct path

Not every popular PHP extension is a core extension accepted by docker-php-ext-install. PECL-distributed modules use a different sequence:

RUN pecl install <extension> 
    && docker-php-ext-enable <extension>

Install any system development libraries required by that PECL module before running pecl install. The PECL command downloads and builds the module; docker-php-ext-enable creates the PHP configuration needed to load it. Do not assume that a module name found in a tutorial is a core extension just because it is commonly used with PHP.

Question Core extension PECL extension
Where does the code come from? PHP source bundled with the official image PECL package installed during the build
Primary build command docker-php-ext-install pecl install
Custom configuration Use docker-php-ext-configure when required Use the PECL build options and prerequisites documented for that module
How is a shared module loaded? The install process handles the core extension’s installation; enable only when appropriate Run docker-php-ext-enable after installation

Using parallel compilation safely

Add -j$(nproc) to docker-php-ext-install when the builder has sufficient CPU and memory:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #4
BSIMB 15.6" Digital Family Calendar & Chore Chart, No Subscription Fees
  • Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
  • Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
  • All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
  • Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
  • Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.
RUN docker-php-ext-install -j$(nproc) gd

Parallel jobs can shorten a build, but they also increase concurrent memory use. If a build is killed, the Docker builder runs out of memory, or compiler processes fail intermittently, reduce the job count or omit -j$(nproc) and build serially. The extension and its dependencies must remain the same; only the compilation scheduling changes.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Keeping production images small

Compilation needs toolchains, headers and package metadata that a running application may not need. Plan the Dockerfile so build-only material does not become part of the final runtime image.

  • Remove Debian package indexes with rm -rf /var/lib/apt/lists/* in the same layer as apt-get update.
  • Keep installation and cleanup in one RUN instruction; deleting files in a later layer does not remove their bytes from earlier layers.
  • Use a builder stage when your production design separates compilation from runtime. Copy the resulting application and required runtime artifacts into the final image, while leaving compilers and development headers behind.
  • If you manually run docker-php-source extract, remove the extracted source in the same image layer after compilation. The configure and install helpers normally manage source extraction for their documented use cases.

Do not remove a library that the compiled extension needs at runtime merely because it was installed as a development dependency. Distinguish runtime libraries from headers and compiler packages before pruning.

Troubleshooting common failures

The command says an extension is unavailable

First run php -m and confirm the module is not already present. Then verify that the module is a core extension supplied by the PHP source in your selected image. If it is distributed through PECL, switch to pecl install and enable the resulting module. A module name alone does not tell you which installer it requires.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The compiler cannot find a header or library

This usually means a development package was omitted or the package name belongs to a different base distribution. Check the image tag, determine whether it is Debian-based or Alpine-based, and install the matching development headers before rerunning the helper script. Read the first missing-file line in the compiler output; later errors are often consequences of that omission.

GD builds but lacks JPEG or FreeType support

Install the corresponding native development libraries and run docker-php-ext-configure gd --with-freetype --with-jpeg before compiling. Without the configure flags, the build may succeed while optional features remain unavailable. Confirm the result with php -i after the image is built.

Package installation works locally but fails after changing the PHP tag

Package names and configure flags are tied to the PHP tag’s underlying distribution and version. Recheck the tag before changing commands. A Dockerfile written for one Debian release or Alpine release should be treated as an example, not a universal package manifest.

The image becomes unexpectedly large

Inspect whether package indexes, compilers, extracted PHP source or development headers remain in the final image. Move compilation to a builder stage where appropriate, clean package indexes in the installation layer, and remove manually extracted source in that same layer.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

A build fails only with parallel jobs

Retry without -j$(nproc) or with a smaller fixed job count. This separates resource pressure from a genuine compiler or dependency error. Once the serial build succeeds, increase parallelism gradually if the builder has adequate memory.

A practical decision checklist

  • Is the base image an official PHP cli, apache or fpm tag that matches the application?
  • Does php -m already list the requested module?
  • Is the module part of the bundled PHP source, or does it come from PECL?
  • Which Debian or Alpine development libraries and headers does it require?
  • Does it need docker-php-ext-configure flags for optional features?
  • Can the builder handle -j$(nproc), or should compilation be serial?
  • Are apt indexes cleaned in the same layer as installation?
  • Will build-only tools and manually extracted source stay out of the runtime image?
  • After building, does php -m or php -i confirm the expected module and features?

Validating the finished image

Build the image, then inspect PHP from inside that exact image rather than from the host:

docker build -t php-app .
docker run --rm php-app php -m
docker run --rm php-app php -i

Use the module list to verify loading and the detailed configuration output to verify optional capabilities such as GD’s image-format support. This final check catches cases where compilation completed but the module was not enabled, where a different PHP binary is being inspected, or where optional configure flags were omitted.

Bottom line for choosing the installer

Use docker-php-ext-install for a PHP core extension available in the official image’s source, after installing its operating-system development dependencies. Add docker-php-ext-configure when optional features need explicit flags. Use PECL for PECL-distributed modules, then enable them with docker-php-ext-enable. Verify first, match package commands to the image’s base distribution, compile with sensible parallelism, and clean build material as part of the image design.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

DockerDockerfileGDPECLPHPPHP extensions

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
Windows Errors? Fix Them Before They SpreadFree repair scan
Outdated Drivers Are Slowing You DownFree scan - exact matches

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.