Install the Microsoft ODBC driver for SQL Server (macOS)
This article explains how to install the Microsoft ODBC Driver for SQL Server on macOS. It also includes instructions for the optional command-line tools for SQL Server (
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.
The Microsoft ODBC driver for SQL Server on macOS is only supported on the x64 architecture through version 17.7. Apple ARM64 support was added starting with version 17.8. The architecture will be detected and the correct package will be automatically installed by the Homebrew formula. If your command prompt is running in x64 emulation mode on ARM64, the x64 package will be installed. If you're not running in emulation mode in your command prompt, the ARM64 package will be installed.
Additionally, the Homebrew default directory changed with the ARM64 architecture, to
/opt/homebrew. The paths in the Driver files section use the x64 Homebrew paths, which default to
/usr/local, so your file paths will vary accordingly.
Microsoft ODBC 18
To install Microsoft ODBC driver 18 for SQL Server on macOS, run the following commands:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release brew update HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18
The following sections provide instructions for installing previous versions of the Microsoft ODBC driver on macOS.
Microsoft ODBC 17
To install Microsoft ODBC driver 17 for SQL Server on macOS, run the following commands:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release brew update HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql17 mssql-tools
If you installed the v17
msodbcsql package that was briefly available, you should remove it before installing the
msodbcsql17 package. This will avoid conflicts. The
msodbcsql17 package can be installed side by side with the
msodbcsql v13 package.
Use the following commands to install the Microsoft ODBC driver 13.1 for SQL Server on OS X 10.11 (El Capitan) and macOS 10.12 (Sierra):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release brew update brew install firstname.lastname@example.org email@example.com
The ODBC driver on macOS consists of the following components:
|libmsodbcsql.18.dylib or libmsodbcsql.17.dylib or libmsodbcsql.13.dylib||The dynamic library (
||The accompanying resource file for the driver library. This file is installed in
|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.
msodbcsql.h is installed in
|LICENSE.txt||The text file that contains the terms of the End-User License Agreement. This file is placed in
|RELEASE_NOTES||The text file that contains release notes. This file is placed in
Resource file loading
The driver needs to load the resource file in order to function. This file is called
msodbcsqlr13.rll depending on the driver version. The location of the
.rll file is relative to the location of the driver itself (
dylib), as noted in the component table. As of version 17.1 the driver also attempts to load the
.rll from the default directory if loading from the relative path fails. The default resource file path on macOS is
Some users encounter an issue when trying to connect after installing the ODBC driver and receive an error like:
" [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server' : file not found (0) (SQLDriverConnect)". It may be the case that unixODBC isn't configured correctly to find registered drivers. In these cases, creating symbolic links can resolve the issue.
sudo ln -s /usr/local/etc/odbcinst.ini /etc/odbcinst.ini sudo ln -s /usr/local/etc/odbc.ini /etc/odbc.ini
For other cases where you're unable to make a connection to SQL Server using the ODBC driver, see the known issues article on troubleshooting connection problems.
If brew is having trouble finding the formulas, make sure you didn't skip the install step:
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
After installing the driver, you can try the C++ ODBC example application. For more information about developing ODBC applications, see Developing Applications.
For more information, see the ODBC driver release notes and system requirements.
Submit and view feedback for