CascadiaPHP 2024

Installing a PHP extension on Windows

There are two ways to load a PHP extension on Windows: either compile it into PHP, or load the DLL. Loading a pre-compiled extension is the easiest and preferred way.

To load an extension, it has to be available as a .dll file on the system. All the extensions are automatically and periodically compiled by the PHP Group (see next section for the download).

To compile an extension into PHP, please refer to the building from source documentation.

To compile a standalone extension (aka a DLL file), please refer to the building from source documentation. If the DLL file is available neither with the PHP distribution nor in PECL, it may be necessary to compile it before the extension can be used.

Where to find an extension?

PHP extensions are usually called php_*.dll (where the star represents the name of the extension), and they are located under the PHP\ext folder.

PHP ships with the extensions most useful to the majority of developers. They are called bundled extensions.

However, if the bundled extensions do not provide the needed functionality, one extension that does may still be found in » PECL. The PHP Extension Community Library (PECL) is a repository for PHP Extensions, providing a directory of all known extensions and hosting facilities for downloading and developing PHP extensions.

If an extension has been developed for particular uses, it may be hosted on PECL so that others with the same needs can benefit from it. A nice side effect is that it's a good chance to receive feedback, (hopefully) thanks, bug reports and even fixes/patches. Before submitting an extension for hosting on PECL, please read » PECL submit.

Which extension to download?

Many times, there will be several versions of each DLL available:

  • Different version numbers (at least the first two numbers should match)
  • Different thread safety settings
  • Different processor architecture (x86, x64, ...)
  • Different debugging settings
  • etc.

Keep in mind that the extension settings should match all the settings of the PHP executable being used. The following PHP script will tell all about the PHP settings:

Example #1 phpinfo() call


Or from the command line, run:

drive:\path\to\php\executable\php.exe -i

Loading an extension

The most common way to load a PHP extension is to include it in the php.ini configuration file. Please note that many extensions are already present in the php.ini and that the semicolon only needs to be removed to activate them.

Note that, as of PHP 7.2.0, the extension name may be used instead of the extension's file name. As this is OS-independent and easier, especially for newcomers, it becomes the recommended way of specifying extensions to load. File names remain supported for compatibility with prior versions.

; As of PHP 7.2.0, prefer:

However, some web servers are confusing because they do not use the php.ini located alongside the PHP executable. To find out where the actual php.ini resides, look for its path in phpinfo():

Configuration File (php.ini) Path  C:\WINDOWS
Loaded Configuration File   C:\Program Files\PHP\8.2\php.ini

After activating an extension, save php.ini, restart the web server, and check phpinfo() again. The new extension should now have its own section.

Resolving problems

If the extension does not appear in phpinfo(), the logs should be checked to learn where the problem comes from.

If PHP is being used from the command line (CLI), the extension loading error can be read directly on the screen.

If PHP is being used with a web server, the location and format of the logs vary depending on the software. Please read the web server documentation to locate the logs, as it has nothing to do with PHP itself.

Common problems are the location of the DLL and the DLLs it depends on, the value of the "extension_dir" setting inside php.ini and compile-time setting mismatches.

If the problem lies in a compile-time setting mismatch, probably the DLL downloaded is not the right one. Try downloading the extension again with the proper settings. Again, phpinfo() can be of great help.

add a note

User Contributed Notes 4 notes

j dot o dot l dot a dot n at bk dot ru
6 months ago
In order for php to see extensions, it is necessary to specify the root folder when specifying the address to the directory with extensions in php.ini. For example extension_dir = "php/ext"
bk at kaelberer-aio dot de
1 year ago
In addition to the helpful comments of ferdnyc and dario: A few weeks ago I've set up a new W11 using PHP 8.1. (as a module) with Apache. It was working fine.
Today i wanted to install the PECL-extension php-amqp. This extension comes with two additional files that are said to be placed in PHPs main directory. It worked fine running from the command prompt but with Apache the extension failed with "Unable to load dynamic library 'amqp'".
I tried 100 ways to notate paths in php.ini and http.conf: c:, C:, \, \\, /, ". I also installed a new PHP in the root to get rid of the space in the path. It did not help.
When reading dario's comment i stumbeled across him mentioning "path environment variable". I checked that in Window's settings and I realized, that i had added PHP's path to the USER'S path-settings, but not to the SYSTEM'S path. That is why it worked in the command prompt but not when starting Apache as a service. After adding it there it worked fine.
dario at 4assistance dot com
1 year ago
On windows, drop your extension's dependencies into a dir of your choice, but outside of your php install. Add that dir to a path environment variable used by your php. Add <extension_name>.dll to your php's extension_dir, and update your php.ini (unless you're simply testing with php's cli).
ferdnyc at gmail dot com
1 year ago
This is handwaved somewhat in the "Resolving problems" section, but mis-location of (non-extension) DLL files is often a problem when installing PHP extensions on Windows.

Many PHP extensions come with not only the extension DLL, but supplementary DLLs that are required by that extension. (For example, php_luasandbox.dll comes with lua5.1.dll, the lua interpreter it sandboxes.) Those other DLLs should go into the same directory as the php.exe binary, NOT the extension directory.

So, if php_luasandbox.dll is installed at C:\PHP8.1\ext\php_luasandbox.dll, the interpreter would be located at C:\PHP8.1\lua5.1.dll. That allows the PHP binary C:\PHP8.1\php.exe to find those additional DLLs when required.
To Top