pyodbc cannot find the SQL Server ODBC driver on Linux
Can't open lib 'ODBC Driver 17 for SQL Server' : file not foundShort answer
The driver manager looked for a driver library that is not installed or not registered under that name. Install Microsoft's msodbcsql package, then use the exact name odbcinst lists in your connection string. In 2026 that is usually ODBC Driver 18 for SQL Server, not 17. On Debian-based images also install libgssapi-krb5-2.
Fix it fast
1Find out which cause you have
List the drivers unixODBC knows about. The name in your connection string must match one of these lines exactly.
odbcinst -j odbcinst -q -d2Match what you see, then jump to its fix
- 1
odbcinst -q -d prints nothing, or only non-SQL-Server driversNo Microsoft ODBC driver is installed in this machine or imageFix - 2
odbcinst -q -d lists ODBC Driver 18 for SQL Server and the string says 17The connection string names version 17, but version 18 is installedFix - 3
The driver is registered, but the error persists on a minimal imageA library the driver links to is missing on Debian or UbuntuFix
- 1
What does the error look like?
Can't open lib 'ODBC Driver 17 for SQL Server' : file not found
Cause 1 of 3
No Microsoft ODBC driver is installed in this machine or image
1Check
pyodbc only talks to the driver manager. The SQL Server driver is a separate package from Microsoft's repository, and python:slim images do not include it.
odbcinst -q -d
ls /opt/microsoft/2Fix
Add the Microsoft repository and install the driver. This is Microsoft's documented Ubuntu procedure; in a Dockerfile run the same lines as root.
curl -sSL -O https://packages.microsoft.com/config/ubuntu/$(grep VERSION_ID /etc/os-release | cut -d '"' -f 2)/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18
sudo apt-get install -y unixodbc-dev3Verify
The driver now appears in the list.
odbcinst -q -dConfirmed by learn.microsoft.com
Cause 2 of 3
The connection string names version 17, but version 18 is installed
1Check
The name in DRIVER={...} has to be a registered name, character for character.
odbcinst -q -d2Fix
Use the registered name, or install msodbcsql17 if the application needs that exact version (Microsoft still documents it on its install page).
DRIVER={ODBC Driver 18 for SQL Server};SERVER=db.example.com;DATABASE=app
# or, to keep 17
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql173Verify
The name used in the connection string is listed.
odbcinst -q -dConfirmed by learn.microsoft.com
Cause 3 of 3
A library the driver links to is missing on Debian or Ubuntu
1Check
Microsoft's Debian steps say the driver links libgssapi_krb5.so.2 without the package declaring it, so a slim image can lack it.
ldd /opt/microsoft/msodbcsql18/lib64/libmsodbcsql-* | grep "not found"2Fix
Install the missing package.
sudo apt-get install -y libgssapi-krb5-23Verify
ldd reports nothing missing, and the connection works.
ldd /opt/microsoft/msodbcsql18/lib64/libmsodbcsql-* | grep -c "not found"Confirmed by learn.microsoft.com
How do I stop it coming back?
- Put the driver install in the Dockerfile, not in a manual step on one server.
- Read the driver name from odbcinst -q -d when you write the connection string.
- Check the Microsoft page for your distribution version before upgrading the base image.
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Databases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
pip install mysqlclient fails to build on Windows, Linux or macOS
error: metadata-generation-failed
mysqlclient is a C extension.
3 causes, each with a fixDatabases
pip cannot build the mariadb package because mariadb_config is missing
Please make sure, that MariaDB Connector/C is installed on your system.
The mariadb Python package builds against MariaDB Connector/C, and it finds the library through the mariadb_config program.
3 causes, each with a fixDatabases
pip install psycopg2 fails with 'Failed building wheel for psycopg2'
error: Python.h: No such file or directory
psycopg2 is compiled from source when pip finds no ready wheel for your platform.
3 causes, each with a fixDatabases
Python cannot import psycopg2 even though you installed it
No module named 'psycopg2.extensions'
Python found no psycopg2 package in the interpreter that runs your code.
3 causes, each with a fixDatabases
asyncpg InterfaceError: another operation is in progress with SQLAlchemy
InterfaceError raised from a FastAPI endpoint that runs several queries at once
A single database connection can run one operation at a time.
4 causes, each with a fix