Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PHP does not load the sqlsrv or pdo_sqlsrv extension for SQL Server

ErrorUnable to load dynamic library

Short 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.

  • Applies to PHP 8.3, PHP 8.4, Microsoft Drivers for PHP for SQL Server
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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_sqlsrv
  2. 2Match what you see, then jump to its fix

    1. 1Unable to load dynamic libraryThe DLL or .so does not match your PHPFix
    2. 2php -m lists sqlsrv, but the website reports a missing function or driverThe command line loads the drivers but the web server does notFix
    3. 3could not find driver, or Module "sqlsrv" is already loadedpdo_sqlsrv loads before PDO, or an entry is duplicatedFix
    4. 4undefined 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

What does the error look like?

  • Unable to load dynamic library
  • The specified module could not be found
  • Module "sqlsrv" is already loaded
  • could 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_sqlsrv

3Verify

php --ri sqlsrv prints module information with ExtensionVer.

php --ri sqlsrv

Confirmed by learn.microsoft.com

Did this fix it?

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.dll

3Verify

The phpinfo page shows separate sqlsrv and pdo_sqlsrv sections; then delete the page.

sudo systemctl restart php8.4-fpm

Confirmed by learn.microsoft.com

Did this fix it?

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/null

2Fix

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.so

3Verify

PDO lists the sqlsrv driver.

php -r 'print_r(PDO::getAvailableDrivers());'

Confirmed by learn.microsoft.com

Did this fix it?

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 -d

2Fix

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/sqlsrv

3Verify

php --ri sqlsrv and php --ri pdo_sqlsrv both print module information.

php -m | grep -E "sqlsrv|pdo_sqlsrv"

Confirmed by learn.microsoft.com

Did this fix it?

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 fix

Back 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.