Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

pyodbc cannot find the SQL Server ODBC driver on Linux

ErrorCan't open lib 'ODBC Driver 17 for SQL Server' : file not found

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

  • Applies to msodbcsql 18, unixODBC 2.3, Ubuntu 24.04, Python 3.13
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1odbcinst -q -d prints nothing, or only non-SQL-Server driversNo Microsoft ODBC driver is installed in this machine or imageFix
    2. 2odbcinst -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. 3The driver is registered, but the error persists on a minimal imageA library the driver links to is missing on Debian or UbuntuFix

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

3Verify

The driver now appears in the list.

odbcinst -q -d

Confirmed by learn.microsoft.com

Did this fix it?

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

2Fix

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 msodbcsql17

3Verify

The name used in the connection string is listed.

odbcinst -q -d

Confirmed by learn.microsoft.com

Did this fix it?

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

3Verify

ldd reports nothing missing, and the connection works.

ldd /opt/microsoft/msodbcsql18/lib64/libmsodbcsql-* | grep -c "not found"

Confirmed by learn.microsoft.com

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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