The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →The correct way to install PHP’s GD image library depends on how PHP itself was installed. Windows builds load the bundled php_gd.dll from php.ini; source builds enable GD with version-appropriate configure flags and development libraries; package-managed installations require the GD package that matches your PHP version and operating system. After changing configuration, restart the PHP-serving process and verify the web runtime separately from the command-line runtime.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
What PHP GD is and why installation varies
GD is a PHP extension that supplies functions for creating, resizing, cropping, drawing and exporting raster images. It is not a separate application that every PHP installation discovers automatically. The extension must be compiled into PHP or loaded as a shared module, and its available image formats are determined by the libraries and switches selected during the build.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
That is why an instruction written for a Windows binary cannot be copied to a source build, and why a command for one Linux distribution may not apply to another. Start by identifying the PHP runtime used by the application and the way that runtime was installed.
| PHP installation route | GD installation or activation method | Most important qualification |
|---|---|---|
| Windows binary | Enable the bundled DLL in the active php.ini |
PHP 8.0 and later use php_gd.dll; releases before PHP 8.0 used php_gd2.dll |
| Source build on Unix-like systems | Install development libraries, then configure and compile PHP with the flags for that PHP release | Current releases use --enable-gd; optional formats are build-time choices |
| Operating-system package | Install the distribution’s GD package matching the PHP version and SAPI | Package names and restart commands differ by distribution, release and PHP version |
Check the PHP version, SAPI and active configuration first
Before changing anything, establish which PHP executable and configuration your application actually uses. A command-line PHP binary can have a different version, extension directory and php.ini from Apache, PHP-FPM or another web-server integration.
#1 Best Overall
- Run
php --versionto record the CLI PHP version. - Run
php --inito see the CLI configuration file and additional scanned configuration directories. - Run
php -mand look forgd. If it is already listed, GD is enabled for that CLI binary. - For a website, inspect the web runtime rather than assuming it uses the CLI settings. A temporary diagnostic page containing
<?php phpinfo();shows the web server’s PHP version, loaded configuration file and GD section. Remove that page immediately after testing.
Record the PHP minor version (for example, 7.4, 8.0 or 8.1), because configure option names changed in PHP 7.4 and AVIF support was added as an option in PHP 8.1.
Windows: enable the bundled GD DLL
Windows PHP distributions include the GD module as a DLL. You normally do not compile GD yourself; you enable the DLL in the configuration file used by the PHP process serving your application.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute1. Find the configuration file that the application uses
php --ini reports the file used by the CLI executable. That file may not be the one used by a web server. Use the web runtime’s diagnostic output to identify the active php.ini when the website and CLI disagree.
2. Enable the correct DLL name
Open the active php.ini and enable the GD extension line. PHP 8.0 and later use:
extension=php_gd.dllPHP releases before 8.0 used the legacy filename:
extension=php_gd2.dllUse the filename that exists in the PHP installation’s extension directory and matches the PHP release. Do not enable both names at once. If the line is commented, remove the comment marker; if it is absent, add the appropriate extension entry in the extensions section.
3. Restart the serving process
PHP reads php.ini when the process starts. Restart the web server, PHP-FPM process or other PHP-serving process after saving the file. A browser refresh alone does not reload a long-running PHP worker.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Rank #2
4. Verify from both environments
For the CLI, run:
php -mOn Windows, you can filter the result with:
php -m | findstr /I gdThen check the website with a temporary script:
<?php
var_dump(extension_loaded('gd'));
var_dump(function_exists('imagecreatetruecolor'));Both values should be true. Delete the diagnostic script when the check is complete.
Source builds on Unix-like systems
When PHP is compiled from source, GD is selected during the configure step. The PHP Manual states that GD compilation requires libpng and libjpeg. PNG support also requires zlib. You need the development headers and libraries, not merely runtime image packages.
Required libraries
- libpng: required for PNG support and required by a GD source build.
- libjpeg: required by a GD source build and for JPEG support.
- zlib: required for PNG support.
Development-package names vary between operating systems, so identify your distribution and PHP release before installing them. After installing or changing a library, rerun configuration so PHP detects the new headers and linker files.
Configure flags in PHP 7.4 and later
From PHP 7.4 onward, --enable-gd controls whether the GD extension is enabled. The separate --with-external-gd option tells PHP to use an external libgd instead of the bundled library. These choices are not interchangeable:
| Purpose | Flag | When to use it |
|---|---|---|
| Enable GD with the bundled library | --enable-gd |
Normal source builds that use the libgd supplied with PHP |
| Use an external libgd | --with-external-gd together with --enable-gd |
Only when the system’s external libgd is intentionally required and compatible |
| JPEG support | --with-jpeg |
PHP 7.4 and later, when JPEG support is needed |
| WebP support | --with-webp |
When the required WebP development library is available |
| XPM support | --with-xpm |
When XPM images are required and the XPM library is available |
| AVIF support | --with-avif |
Available from PHP 8.1.0; requires the corresponding AVIF capability |
| FreeType text rendering | --with-freetype |
PHP 7.4 and later; detection relies on pkg-config |
Do not add every switch automatically. Each optional switch is a build-time request for a capability and can fail if its development library or detection metadata is missing.
Older PHP releases
Older manuals may show --with-gd and directory-oriented forms such as --with-jpeg-dir, --with-webp-dir or --with-xpm-dir. PHP 7.4 changed several of these names. Use the configure syntax documented for the exact PHP release you are compiling; copying a current flag into an older release, or an old *-dir flag into a current release, can make configuration fail or silently omit a capability.
Run configure with only the features you need
A typical PHP 7.4-or-newer build that needs JPEG, WebP and FreeType might include:
./configure --enable-gd --with-jpeg --with-webp --with-freetypeFor a build that deliberately uses an external libgd, the relevant combination is:
./configure --enable-gd --with-external-gd --with-jpeg --with-webp --with-freetypeThese are configure-stage examples, not complete PHP build recipes. Keep the rest of your existing PHP configure options, and add only switches supported by the PHP version and libraries installed on the machine. If AVIF is needed and the build is PHP 8.1.0 or newer, add --with-avif.
Compile, install and restart
- Install the libpng and libjpeg development files; add zlib and any optional format or FreeType development files required by your selected switches.
- Run
./configurewith the version-appropriate GD flags. - Review the configure summary for GD and the requested formats before compiling. A missing library can cause a configure error or leave a capability disabled.
- Compile and install PHP using the same build procedure and prefix as the existing installation.
- Restart the PHP-serving process so it loads the newly installed binary or module.
- Verify the CLI and web runtimes independently.
The PHP Manual warns that the libpng version used when compiling PHP must match the version linked with GD. If those versions differ, rebuild with a consistent libpng installation rather than treating the warning as harmless.
Package-managed PHP
Distribution packages are usually the simplest route when PHP came from an operating-system repository, but the package name and service-management command are distribution-specific. The canonical PHP installation documentation does not provide one command that is correct for every distribution and PHP version.
- Identify the operating system, release, PHP minor version and SAPI (CLI, Apache module or PHP-FPM).
- Use that distribution’s package manager to locate the GD package matching the PHP version. Avoid installing a package for a different PHP minor release.
- Install the package and note whether it supplies a module, a replacement PHP build or both.
- Restart the PHP-serving process named by the distribution’s documentation.
- Run
php -mfor the CLI and use a web-runtime diagnostic page for the application. If only one shows GD, the two SAPIs are using different PHP installations or configuration files.
Do not assume that installing a CLI package changes a separately managed PHP-FPM or web-server runtime. The loaded configuration and extension list are the evidence that matters.
Rank #4
Verify that GD and the required formats are really available
CLI verification
Run php -m and confirm that gd appears. To inspect the loaded configuration, use php --ini. A more focused diagnostic script can report the extension and its capabilities:
<?php
var_dump(extension_loaded('gd'));
var_dump(function_exists('gd_info'));
if (function_exists('gd_info')) {
print_r(gd_info());
}The gd_info() output identifies capabilities exposed by the loaded build. Check it when the application needs a particular format rather than assuming that installing GD enables every format.
Web-runtime verification
Place the same checks in a temporary page served by the application’s actual web server. This catches the common case in which the CLI has GD but the website runs another PHP version or another php.ini. Keep diagnostic pages private and remove them after testing because configuration output can disclose paths and environment details.
Functional smoke test
Checking that imagecreatetruecolor exists confirms that a core GD function can be called. A real application should also exercise the formats it depends on—for example, its PNG, JPEG or WebP upload and thumbnail path—because GD can be loaded while a particular optional capability is absent.
Troubleshooting common failures
“Call to undefined function imagecreatetruecolor()”
The code is running without GD in that PHP runtime. Check extension_loaded('gd'), inspect the web runtime’s active php.ini, enable or install the module there, and restart the serving process.
GD appears in CLI output but not on the website
This indicates different PHP configurations or SAPIs. Compare the PHP version, loaded configuration file and extension list from the CLI and a temporary web diagnostic page. Make the change in the configuration actually used by the website; changing the CLI file alone will not fix the web process.
Windows reports that the GD DLL cannot be loaded
Confirm the filename for the PHP generation: php_gd.dll for PHP 8.0 and later, or php_gd2.dll before PHP 8.0. Check that the extension entry is in the active php.ini, then restart the serving process. A DLL from a different PHP installation or release is not a substitute for the bundled module.
Configure cannot find PNG or JPEG libraries
The runtime libraries alone are insufficient for a source build. Install the corresponding development headers and linker files, rerun ./configure, and inspect the configuration summary. PNG support also needs zlib.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Configuration warns about incompatible libpng versions
Use a single, consistent libpng version for the PHP build and GD link. The manual specifically warns that the libpng version compiled with PHP must match the version linked with GD. Cleanly reconfigure and rebuild after correcting the library paths.
GD loads but WebP, AVIF, XPM or FreeType is missing
Those capabilities are optional. Confirm that the PHP release supports the switch, that the corresponding development library is installed, and that the switch was present during configuration. AVIF’s GD switch is available from PHP 8.1.0; FreeType uses --with-freetype from PHP 7.4 onward and relies on pkg-config. A capability omitted at build time cannot normally be enabled by editing php.ini.
The change has no effect after editing php.ini
PHP reads configuration at process startup. Restart the relevant web server, PHP-FPM process or other PHP-serving process, and verify the loaded configuration again. If the restart did not change the reported file or extension list, you edited a configuration that the application does not use.
Quick Recap
Choose the right installation path
| Your situation | Recommended path | What to verify before declaring success |
|---|---|---|
| Standard Windows PHP binary | Enable the bundled DLL in the active php.ini |
Correct DLL name, process restart, GD visible in the web runtime |
| PHP compiled from source | Install development libraries and configure GD with release-appropriate flags | libpng/libjpeg requirements, zlib for PNG, optional switches and configure summary |
| PHP supplied by an operating-system repository | Install the matching distribution GD package | Package matches PHP minor version and SAPI; restart command is distribution-specific |
| CLI works but the application fails | Diagnose the web SAPI independently | Web version, php.ini path and extension list, not just CLI output |
Final checklist
- Identify the PHP version and the runtime that serves the application.
- Use the installation method that matches PHP: DLL activation, source compilation or a distribution package.
- For source builds, provide libpng and libjpeg; add zlib for PNG support.
- Use
--enable-gdfor current source builds and add--with-external-gdonly when an external libgd is intentional. - Use optional format and FreeType switches only when the PHP version and required libraries support them.
- Remember that PHP 7.4 changed several configure option names and that AVIF support begins with PHP 8.1.0.
- On Windows, select
php_gd.dllfrom PHP 8.0 onward andphp_gd2.dllbefore PHP 8.0. - Restart the serving process and test both CLI and web configurations.
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.
Free tools Windows power users keep installed
One-click scans. No signup required.
