PHP does not load the sqlsrv or pdo_sqlsrv extension for SQL Server
Unable to load dynamic libraryShort answer
The drivers are normal PHP extensions: installing the file is not enough, the php.ini that your web process reads must load the matching file, and the process must be restarted. Check which php.ini is active, match the file to your PHP version, architecture and thread safety, and load PDO before pdo_sqlsrv.
Fix it fast
1Find out which cause you have
Ask the exact PHP your app uses which config it loaded and whether the extension is present. Run it for the CLI, then check the web process separately.
php --ini php --ri sqlsrv php --ri pdo_sqlsrv2Match what you see, then jump to its fix
- 1
Unable to load dynamic libraryThe DLL or .so does not match your PHPFix - 2
php -m lists sqlsrv, but the website reports a missing function or driverThe command line loads the drivers but the web server does notFix - 3
could not find driver, or Module "sqlsrv" is already loadedpdo_sqlsrv loads before PDO, or an entry is duplicatedFix - 4
undefined symbol or a shared-library error on Linux and macOS, sql.h not found while buildingThe Microsoft ODBC driver or its build tools are missingFix
- 1
What does the error look like?
Unable to load dynamic libraryThe specified module could not be foundModule "sqlsrv" is already loadedcould not find driver
Cause 1 of 4
The DLL or .so does not match your PHP
1Check
The file must match the PHP minor version, architecture and thread-safety mode. Read these from php -i.
php -i | grep -E "PHP Version|Thread Safety|Architecture|extension_dir"2Fix
Install with PIE, or copy the exact file for your runtime into extension_dir and name that file in php.ini. Do not mix thread-safe and non-thread-safe, or 32-bit and 64-bit, files.
pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv3Verify
php --ri sqlsrv prints module information with ExtensionVer.
php --ri sqlsrvConfirmed by learn.microsoft.com
Cause 2 of 4
The command line loads the drivers but the web server does not
1Check
Each PHP runtime (CLI, Apache module, PHP-FPM, IIS FastCGI) can use another executable and configuration. Changing the CLI config does not change the others.
# temporary page, restrict access and delete it after
<?php phpinfo();2Fix
Add the extension entry to the php.ini and scan files that the web runtime reports, then restart the web server or PHP-FPM, and any queue workers.
; Linux / macOS
extension=sqlsrv.so
extension=pdo_sqlsrv.so
; Windows (PIE install)
extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll3Verify
The phpinfo page shows separate sqlsrv and pdo_sqlsrv sections; then delete the page.
sudo systemctl restart php8.4-fpmConfirmed by learn.microsoft.com
Cause 3 of 4
pdo_sqlsrv loads before PDO, or an entry is duplicated
1Check
PDO must load before PDO_SQLSRV. When PDO comes from a scanned file such as 10-pdo.ini, the PDO_SQLSRV entry must sit in a later scanned file, not in php.ini. Do not configure both a short and a versioned name for one extension.
php --ini
grep -rn "sqlsrv" $(php --ini | grep -i "scan for additional" | sed 's/.*: //') /etc/php 2>/dev/null2Fix
Put the PDO_SQLSRV entry in a later scanned file such as 30-pdo_sqlsrv.ini, and keep one entry for each extension.
; 30-pdo_sqlsrv.ini
extension=pdo_sqlsrv.so3Verify
PDO lists the sqlsrv driver.
php -r 'print_r(PDO::getAvailableDrivers());'Confirmed by learn.microsoft.com
Cause 4 of 4
The Microsoft ODBC driver or its build tools are missing
1Check
The extension talks to SQL Server through the Microsoft ODBC Driver, and building needs the unixODBC development package, a compiler and the PHP development files.
odbcinst -q -d2Fix
Install the Microsoft ODBC Driver for your system, then the development packages (on Ubuntu or Debian: unixodbc-dev, plus g++, make and the PHP dev package) and run PIE again.
sudo apt-get install unixodbc-dev g++ make git
pie install microsoft/sqlsrv3Verify
php --ri sqlsrv and php --ri pdo_sqlsrv both print module information.
php -m | grep -E "sqlsrv|pdo_sqlsrv"Confirmed by learn.microsoft.com
How do I stop it coming back?
- Write down the exact PHP executable, php.ini and scan directory before you change anything.
- Restart every process that loads PHP after changing an extension, including queue workers.
- Use PIE rather than PECL for these drivers; Microsoft's page calls PIE the supported installer for current releases.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
php artisan migrate stops with could not find driver
could not find driver (Connection: mysql, SQL: select * from information_schema.tables ...)
Laravel talks to the database through a PDO driver, and this error means the PHP that runs artisan has none for your DB_CONNECTION.
3 causes, each with a fixBack end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack end
Apache returns 403 when a URL contains %3F
a request like /page%3Fname=test is refused while /page?name=test works
Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.
2 causes, each with a fixBack end
Apache returns 500 with Premature end of script headers
500 Internal Server Error
Apache ran your script, but the script printed no valid HTTP header before its output.
3 causes, each with a fixBack end
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fixBack end
AWS SDK for PHP cannot get credentials from the instance profile metadata server
Error retrieving credentials from the instance profile metadata server.
The SDK tries the EC2 instance metadata service when it has no valid credentials from anywhere earlier in its chain.
4 causes, each with a fix