Edit

Install the Microsoft ODBC driver for SQL Server (Linux)

This article explains how to install the Microsoft ODBC Driver for SQL Server on Linux. It also includes instructions for the optional command-line tools for SQL Server (bcp and sqlcmd) and the unixODBC development headers.

This article provides commands for installing the ODBC driver from the bash shell. If you want to download the packages directly, see Download ODBC Driver for SQL Server.

Choose a driver version

Use Driver 18 for new applications. Driver 17 remains supported for applications that require version 17 behavior. Before you upgrade an application from Driver 17 to Driver 18, review the major version differences, including the change to encryption defaults. For support dates, see the support lifecycle.

The following table shows the driver and command-line tools packages:

Version Driver package Optional tools package Tools path
18 msodbcsql18 mssql-tools18 /opt/mssql-tools18/bin
17 msodbcsql17 mssql-tools /opt/mssql-tools/bin

Microsoft ODBC 18

The following sections explain how to install the Microsoft ODBC driver 18 from the bash shell for different Linux distributions. Supported distributions are Alpine Linux, Debian, Red Hat Enterprise Linux (RHEL), Oracle Linux, SUSE Linux Enterprise Server (SLES), Ubuntu, and Azure Linux. Starting with version 18.4, to accept the End-User License Agreement (EULA) automatically when installing the non-Alpine Linux (.deb or .rpm) driver, you can create the file /opt/microsoft/msodbcsql18/ACCEPT_EULA.

set -euo pipefail

case $(uname -m) in
    x86_64) architecture="amd64" ;;
    aarch64|arm64) architecture="arm64" ;;
    *) architecture="unsupported" ;;
esac
if [[ "unsupported" == "$architecture" ]];
then
    echo "Alpine architecture $(uname -m) is not currently supported."
    exit 1
fi

if ! command -v gpg >/dev/null 2>&1; then
    echo "Install gnupg before running this block."
    exit 1
fi

driver_package="msodbcsql18_18.7.1.1-1_${architecture}.apk"
tools_package="mssql-tools18_18.7.1.1-1_${architecture}.apk"
driver_signature="${driver_package%.apk}.sig"
tools_signature="${tools_package%.apk}.sig"

# Download the packages and signatures.
curl -fSLO "https://download.microsoft.com/download/ade174b7-8cea-4543-91a6-c33ae320c2f0/$driver_package"
curl -fSLO "https://download.microsoft.com/download/a5dcc5e7-6124-49d3-8df4-48d738a0e784/$tools_package"
curl -fSLO "https://download.microsoft.com/download/ade174b7-8cea-4543-91a6-c33ae320c2f0/$driver_signature"
curl -fSLO "https://download.microsoft.com/download/a5dcc5e7-6124-49d3-8df4-48d738a0e784/$tools_signature"
curl -fSL https://packages.microsoft.com/keys/microsoft.asc -o microsoft.asc

# Verify the package signatures before installation.
gpg --import microsoft.asc
gpg --verify "$driver_signature" "$driver_package"
gpg --verify "$tools_signature" "$tools_package"

# Install the packages.
sudo apk add --allow-untrusted "$driver_package"
sudo apk add --allow-untrusted "$tools_package"

Note

Driver 17.5 and later versions support Alpine.

Microsoft ODBC 17

The following sections explain how to install the Microsoft ODBC driver 17 from the bash shell for different Linux distributions.

Important

If you installed the v17 msodbcsql package that was briefly available, remove it before installing the msodbcsql17 package to avoid conflicts. You can install the msodbcsql17 package side by side with the msodbcsql v13 package.

set -euo pipefail

if [[ "$(uname -m)" != "x86_64" ]]; then
    echo "Driver 17 Alpine packages are available only for x86_64." >&2
    exit 1
fi

if ! command -v gpg >/dev/null 2>&1; then
    echo "Install gnupg before running this block."
    exit 1
fi

driver_package="msodbcsql17_17.11.1.1-1_amd64.apk"
tools_package="mssql-tools_17.11.1.1-1_amd64.apk"
driver_signature="${driver_package%.apk}.sig"
tools_signature="${tools_package%.apk}.sig"

# Download the packages and signatures.
curl -fSLO "https://download.microsoft.com/download/607ebe2c-e17c-4c34-b367-10a75b83bef9/$driver_package"
curl -fSLO "https://download.microsoft.com/download/aca0282f-6a67-49c0-ae08-887d59d16d1a/$tools_package"
curl -fSLO "https://download.microsoft.com/download/607ebe2c-e17c-4c34-b367-10a75b83bef9/$driver_signature"
curl -fSLO "https://download.microsoft.com/download/aca0282f-6a67-49c0-ae08-887d59d16d1a/$tools_signature"
curl -fSL https://packages.microsoft.com/keys/microsoft.asc -o microsoft.asc

# Verify the package signatures before installation.
gpg --import microsoft.asc
gpg --verify "$driver_signature" "$driver_package"
gpg --verify "$tools_signature" "$tools_package"

# Install the packages.
sudo apk add --allow-untrusted "$driver_package"
sudo apk add --allow-untrusted "$tools_package"

Note

Driver 17.5 and later versions support Alpine.

Update or verify a driver installation

To update a driver you installed from a Linux package repository, refresh the package metadata and update the package for the same major version. For distributions with Driver 17 installation instructions in this article, replace msodbcsql18 with msodbcsql17 to update Driver 17. The Azure Linux commands apply to Driver 18. To move between major versions, install the other package and configure your application to request its driver name.

Distribution Update command
Debian or Ubuntu sudo apt-get update && sudo ACCEPT_EULA=Y apt-get install --only-upgrade -y msodbcsql18
Red Hat Enterprise Linux or Oracle Linux sudo ACCEPT_EULA=Y yum update -y msodbcsql18
SUSE Linux Enterprise Server sudo zypper refresh && sudo ACCEPT_EULA=Y zypper update -y msodbcsql18
Azure Linux sudo ACCEPT_EULA=Y tdnf upgrade -y msodbcsql18

For Alpine, download and install the updated APK for the installed major version and system architecture. Driver 18 supports the amd64 and arm64 packages shown in the installation instructions. Driver 17 uses the amd64 package:

The update commands require curl and gpg. If either is missing, install them with sudo apk add curl gnupg.

set -e
case "$(uname -m)" in
    x86_64) architecture="amd64" ;;
    aarch64|arm64) architecture="arm64" ;;
    *) echo "Unsupported Alpine architecture: $(uname -m)" >&2; exit 1 ;;
esac

driver_apk="msodbcsql18_18.7.1.1-1_${architecture}.apk"
curl -fSL -O "https://download.microsoft.com/download/ade174b7-8cea-4543-91a6-c33ae320c2f0/$driver_apk"
curl -fSL -o "$driver_apk.sig" "https://download.microsoft.com/download/ade174b7-8cea-4543-91a6-c33ae320c2f0/${driver_apk%.apk}.sig"
curl -fSL https://packages.microsoft.com/keys/microsoft.asc -o microsoft.asc
gpg --import microsoft.asc
gpg --verify "$driver_apk.sig" "$driver_apk"
sudo apk add --allow-untrusted "$driver_apk"
rm "$driver_apk" "$driver_apk.sig" microsoft.asc

For Driver 17, download and install the amd64 package:

set -e
if [[ "$(uname -m)" != "x86_64" ]]; then
    echo "Driver 17 Alpine packages are available only for x86_64." >&2
    exit 1
fi

driver_apk="msodbcsql17_17.11.1.1-1_amd64.apk"
curl -fSL -O "https://download.microsoft.com/download/607ebe2c-e17c-4c34-b367-10a75b83bef9/$driver_apk"
curl -fSL -o "$driver_apk.sig" "https://download.microsoft.com/download/607ebe2c-e17c-4c34-b367-10a75b83bef9/${driver_apk%.apk}.sig"
curl -fSL https://packages.microsoft.com/keys/microsoft.asc -o microsoft.asc
gpg --import microsoft.asc
gpg --verify "$driver_apk.sig" "$driver_apk"
sudo apk add --allow-untrusted "$driver_apk"
rm "$driver_apk" "$driver_apk.sig" microsoft.asc

After you install or update a driver, set driver_version to 17 or 18, and then check its unixODBC registration and system architecture:

Driver version driver_package driver_name
18 msodbcsql18 ODBC Driver 18 for SQL Server
17 msodbcsql17 ODBC Driver 17 for SQL Server
set -e
driver_version=18
driver_package="msodbcsql${driver_version}"
driver_name="ODBC Driver ${driver_version} for SQL Server"

odbcinst -q -d -n "$driver_name"
uname -m

The registration query prints the driver name in brackets. uname -m reports the system architecture. Use the package query for your distribution to check the installed package version and architecture:

Distribution Package query
Debian or Ubuntu dpkg-query -W -f='${Package} ${Version} ${Architecture}\n' "$driver_package"
Red Hat Enterprise Linux, Oracle Linux, SUSE Linux Enterprise Server, or Azure Linux rpm -q --qf '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$driver_package"
Alpine awk -v package="$driver_package" 'index($0, "P:") == 1 { name = substr($0, 3) } name == package && index($0, "V:") == 1 { version = substr($0, 3) } name == package && index($0, "A:") == 1 { printf "%s %s %s\n", name, version, substr($0, 3); found = 1 } END { if (!found) exit 1 }' /lib/apk/db/installed

The package query returns the package name, installed version, and package architecture. These commands don't connect to a database.

Remove or reinstall Driver 17 or Driver 18

Close applications that use the driver before removing it. For distributions with Driver 17 installation instructions in this article, replace msodbcsql18 with msodbcsql17 to remove Driver 17. The Azure Linux command applies to Driver 18.

Distribution Removal command
Debian or Ubuntu sudo apt-get remove msodbcsql18
Red Hat Enterprise Linux or Oracle Linux sudo yum remove msodbcsql18
SUSE Linux Enterprise Server sudo zypper remove msodbcsql18
Azure Linux sudo tdnf remove msodbcsql18
Alpine sudo apk add unixodbc && sudo apk del msodbcsql18

Dependent applications or tools might also be removed. If your package manager asks for confirmation, review the proposed removals before accepting. On Red Hat Enterprise Linux and Oracle Linux releases where yum uses DNF, add --setopt=clean_requirements_on_remove=0 to the removal command to retain unixODBC for the registration check. For Driver 17, replace msodbcsql18 with msodbcsql17.

On Alpine, install unixODBC explicitly before removing the driver so odbcinst remains available for the registration check. apk del retains the driver if installed tools still depend on it. If you installed the optional tools, replace the Alpine command in the preceding table with:

sudo apk add unixodbc
sudo apk del mssql-tools18 msodbcsql18

For Driver 17, use sudo apk add unixodbc followed by sudo apk del mssql-tools msodbcsql17. Review the dependent applications before removing these packages, then repeat the registration query.

After removal, run odbcinst -q -d. If it lists driver names, confirm that the removed driver name isn't listed. If it reports SQLGetPrivateProfileString failed, run odbcinst -j and check the DRIVERS path it reports. If the driver configuration file exists, is readable, and contains no driver registrations, no drivers remain registered. If the file is missing, unreadable, or still contains the removed driver's entry, resolve that configuration issue before treating removal as complete. To reinstall, repeat the installation commands for the same distribution and major version, then repeat verification.

Removing a driver can prevent applications that request its driver name from connecting. Don't delete driver files or the driver-manager configuration file. If a stale registration blocks installation, see Previous driver version conflict for the targeted recovery steps.

Earlier versions

The following sections provide installation instructions for earlier versions of the Microsoft ODBC driver:

ODBC 13.1

The following sections explain how to install the Microsoft ODBC driver 13.1 from the bash shell for different Linux distributions.

debian_version=$(grep VERSION_ID /etc/os-release | cut -d '"' -f 2 | cut -d '.' -f 1)
case "$debian_version" in
    8) ;;
    *) echo "Debian $debian_version is not currently supported." >&2; exit 1 ;;
esac

# Download the package to configure the Microsoft repo
curl -fsSLO "https://packages.microsoft.com/config/debian/$debian_version/packages-microsoft-prod.deb" || exit 1
# Install the package
sudo dpkg -i packages-microsoft-prod.deb
# Delete the file
rm packages-microsoft-prod.deb

sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install msodbcsql
# optional: for bcp and sqlcmd
sudo ACCEPT_EULA=Y apt-get install mssql-tools
echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc
source ~/.bashrc
# optional: for unixODBC development headers
sudo apt-get install unixodbc-dev

ODBC 13

The following sections explain how to install the Microsoft ODBC driver 13 from the bash shell for different Linux distributions.

rhel_version=$(grep VERSION_ID /etc/os-release | cut -d '"' -f 2 | cut -d '.' -f 1)
case "$rhel_version" in
    6|7) ;;
    *) echo "RHEL $rhel_version is not currently supported." >&2; exit 1 ;;
esac

# Download the package to configure the Microsoft repo
curl -fsSLO "https://packages.microsoft.com/config/rhel/$rhel_version/packages-microsoft-prod.rpm" || exit 1
# Install the package
sudo yum install packages-microsoft-prod.rpm
# Delete the file
rm packages-microsoft-prod.rpm

sudo yum update
sudo yum remove unixODBC #to avoid conflicts
sudo ACCEPT_EULA=Y yum install msodbcsql-13.0.1.0-1 mssql-tools-14.0.2.0-1
sudo yum install unixODBC-utf16-devel #this step is optional but recommended*
#Create symlinks for tools
sudo ln -sfn /opt/mssql-tools/bin/sqlcmd-13.0.1.0 /usr/bin/sqlcmd
sudo ln -sfn /opt/mssql-tools/bin/bcp-13.0.1.0 /usr/bin/bcp

Offline installation for ODBC 13

To install the Microsoft ODBC Driver 13 without an Internet connection, manually resolve these direct package dependencies:

  • Ubuntu: libc6 (>= 2.21), libstdc++6 (>= 4.9), libkrb5-3, libcurl3, openssl, debconf (>= 0.5), unixODBC (>= 2.3.1-1)
  • Red Hat: glibc, e2fsprogs, krb5-libs, openssl, unixODBC
  • SUSE: glibc, libuuid1, krb5, openssl, unixODBC

Each package has its own dependencies. For package manager guidance, see the documentation for Red Hat, Ubuntu, and SUSE.

You can manually download all the dependent packages and place them together on the installation computer. Then, manually install each package in turn, finishing with the Microsoft ODBC Driver 13 package.

sudo yum install glibc e2fsprogs krb5-libs openssl unixODBC unixODBC-devel #install dependencies
sudo rpm -i  msodbcsql-13.1.X.X-X.x86_64.rpm #install the Driver

ODBC 11

The following sections explain how to install the Microsoft ODBC driver 11 on Linux. Before you can use the driver, install the unixODBC driver manager. For more information, see Installing the Driver Manager.

Install Driver 11

Important

Use the archive that matches your distribution: Red Hat Linux uses msodbcsql-11.0.2270.0.tar.gz, and SUSE Linux uses msodbcsql-11.0.2260.0.tar.gz.

To install the driver:

  1. Confirm that you have root permission.

  2. Download the driver.

    Distribution Driver SHA256 hash
    Red Hat 5 msodbcsql-11.0.2270.0.tar.gz 178280daf01a49b8322cd902b6440979adacd594c01cd2a1f081dda23dbfb343
    Red Hat 6 msodbcsql-11.0.2270.0.tar.gz e9b6bd33d174c7753b3a3f2d541713fbc156b46254484a169caa3f459dd828f7
    SUSE Linux msodbcsql-11.0.2260.0.tar.gz 86d1c5842be4f0095234a9455e18a04fdf4cc7960ec0255b37258112e2391ef5
  3. Change to the directory where you downloaded the archive. To extract the Red Hat package, run:

    tar xvzf msodbcsql-11.0.2270.0.tar.gz
    

    To extract the SUSE package, run:

    tar xvzf msodbcsql-11.0.2260.0.tar.gz
    
  4. Change to the extracted directory that matches your archive version. You should see a file called install.sh.

  5. To see a list of the available installation options, run the following command:

    ./install.sh
    
  6. Make a backup of odbcinst.ini. The driver installation updates odbcinst.ini. odbcinst.ini contains the list of drivers that are registered with the unixODBC Driver Manager. To discover the location of odbcinst.ini on your computer, run the following command:

    odbc_config --odbcinstini
    
  7. Before you install the driver, run the following command:

    ./install.sh verify
    

    The output of ./install.sh verify reports if your computer has the required software to support the ODBC driver on Linux.

  8. When you're ready to install the ODBC driver on Linux, run the command:

    ./install.sh install
    

    To set nondefault binary or library directories, pass --bin-dir=<directory> or --lib-dir=<directory> after the install option.

  9. After reviewing the license agreement, type YES to continue with the installation.

The driver library is installed in /opt/microsoft/msodbcsql/lib64. Red Hat installs version 11.0.2270.0 and SUSE installs version 11.0.2260.0. Each version's support files are installed in its corresponding directory under /opt/microsoft/msodbcsql. The package also installs versioned bcp and sqlcmd utilities under /opt/microsoft/msodbcsql/bin and creates links in /usr/bin by default. If you used the --lib-dir or --bin-dir option, substitute the paths you specified.

To verify that the Microsoft ODBC driver on Linux was registered successfully, run the following command:

odbcinst -q -d -n "ODBC Driver 11 for SQL Server"

Uninstall

Uninstall the ODBC driver 11 on Linux by running the following commands:

Caution

These commands remove the Driver 11 libraries, utilities, and support files for the two listed package versions. Check the paths before you run them. If you used the --lib-dir or --bin-dir option, substitute the paths you specified.

set -e
odbcinst -u -d -n "ODBC Driver 11 for SQL Server"
for tool in bcp sqlcmd; do
    link="/usr/bin/$tool"
    if [ -L "$link" ]; then
        target=$(readlink "$link")
        case "$target" in
            "/opt/microsoft/msodbcsql/bin/$tool-11.0.2270.0"|"/opt/microsoft/msodbcsql/bin/$tool-11.0.2260.0")
                rm "$link"
                ;;
        esac
    fi
done
rm -f /opt/microsoft/msodbcsql/lib64/libmsodbcsql-11.0.so.2270.0 \
    /opt/microsoft/msodbcsql/lib64/libmsodbcsql-11.0.so.2260.0 \
    /opt/microsoft/msodbcsql/bin/bcp-11.0.2270.0 \
    /opt/microsoft/msodbcsql/bin/bcp-11.0.2260.0 \
    /opt/microsoft/msodbcsql/bin/sqlcmd-11.0.2270.0 \
    /opt/microsoft/msodbcsql/bin/sqlcmd-11.0.2260.0
rm -rf /opt/microsoft/msodbcsql/11.0.2270.0 \
    /opt/microsoft/msodbcsql/11.0.2260.0

Driver files

Key ODBC driver files on Linux include:

Component Description
libmsodbcsql-18.X.so.X.X, libmsodbcsql-17.X.so.X.X, or libmsodbcsql-13.X.so.X.X The main shared object (so) library for the driver. The installation path is /opt/microsoft/msodbcsql18/lib64/ for Driver 18, /opt/microsoft/msodbcsql17/lib64/ for Driver 17, and /opt/microsoft/msodbcsql/lib64/ for Driver 13.
msodbcsqlr18.rll, msodbcsqlr17.rll, or msodbcsqlr13.rll The resource file that accompanies the driver library. The installation path is [driver .so directory]../share/resources/en_US/.
msodbcsql.h The header file that contains all of the new definitions needed to use the driver.

Note: You can't reference msodbcsql.h and odbcss.h in the same program.

The installation path is /opt/microsoft/msodbcsql18/include/ for Driver 18, /opt/microsoft/msodbcsql17/include/ for Driver 17, and /opt/microsoft/msodbcsql/include/ for Driver 13.
LICENSE.txt The text file that contains the terms of the End-User License Agreement. The installation path is /usr/share/doc/msodbcsql18/ for Driver 18, /usr/share/doc/msodbcsql17/ for Driver 17, and /usr/share/doc/msodbcsql/ for Driver 13.
RELEASE_NOTES The text file that contains release notes. The installation path is /usr/share/doc/msodbcsql18/ for Driver 18, /usr/share/doc/msodbcsql17/ for Driver 17, and /usr/share/doc/msodbcsql/ for Driver 13.

Load the resource file

The driver needs to load the resource file to function. This file is called msodbcsqlr18.rll, msodbcsqlr17.rll, or msodbcsqlr13.rll depending on the driver version. The location of the .rll file is relative to the location of the driver itself (so or dylib), as described in the previous table. Starting with version 17.1, if the driver can't load the .rll file from the relative path, it also tries to load the .rll file from the default directory. The default resource file path on Linux is /opt/microsoft/msodbcsql18/share/resources/en_US/ for Driver 18 and /opt/microsoft/msodbcsql17/share/resources/en_US/ for Driver 17.

Troubleshoot

Previous driver version conflict

If you previously installed and registered a driver version with unixODBC, installation might fail with an error such as:

Installation failed, ODBC Driver $1 for SQL Server detected!

To resolve the problem, unregister that driver version with odbcinst. Replace <version> with the number in the error message:

odbcinst -u -d -n "ODBC Driver <version> for SQL Server"

If odbcinst can't unregister the driver, back up odbcinst.ini and remove only the section for the conflicting driver. Don't delete the file or other driver sections. Run odbcinst -j to find the file location.

Package download errors on Debian and Ubuntu

On Debian-based distributions, you might see the following error when you install the packages-microsoft-prod.deb package:

dpkg-deb: error: 'packages-microsoft-prod.deb' is not a Debian format archive

A network interruption or proxy issue might leave the downloaded file corrupted or incomplete, causing this error. To resolve the problem:

  1. Delete the corrupted file and download it again. For Ubuntu:

    rm packages-microsoft-prod.deb
    curl -fsSLO "https://packages.microsoft.com/config/ubuntu/$(grep VERSION_ID /etc/os-release | cut -d '"' -f 2)/packages-microsoft-prod.deb" || exit 1
    

    For Debian, replace ubuntu and use the major version number only:

    rm packages-microsoft-prod.deb
    curl -fsSLO "https://packages.microsoft.com/config/debian/$(grep VERSION_ID /etc/os-release | cut -d '"' -f 2 | cut -d '.' -f 1)/packages-microsoft-prod.deb" || exit 1
    
  2. Verify the download is a valid Debian package (the output should include Debian binary package):

    file packages-microsoft-prod.deb
    
  3. If the download continues to fail, check your network connection and proxy settings, or use wget instead of curl:

    wget https://packages.microsoft.com/config/ubuntu/$(grep VERSION_ID /etc/os-release | cut -d '"' -f 2)/packages-microsoft-prod.deb
    

Connection problems

For more information about connection problems, see the known issues article on troubleshooting connection problems.