Building and developing pymssql

Required software

To build pymssql you should have:

  • Python >= 3.6 including development files. Please research your OS usual software distribution channels, e.g, python-dev or python-devel packages on Linux.
  • Cython - to compile pymssql source files to C.
  • setuptools - for support.
  • setuptools_scm - for extracting version information from git.
  • wheel - for building python wheels.
  • FreeTDS >= 1.2 including development files. Please research your OS usual software distribution channels, e.g, freetds-dev or freetds-devel packages on Linux.
  • GNU gperf - a perfect hash function generator, needed for FreeTDS. On Windows prebuild version is available from Chocolatey.
  • win-iconv (Windows only) - developing pymssql on Windows also requires this library to build FreeTDS.
  • OpenSSL - If you need to connect to Azure make sure FreeTDS is built with SSL support. Please research your OS usual software distribution channels. On Windows one easy way is to get prebuild libraries from Chocolatey.

For testing the follwing is required:

  • Microsoft SQL Server. One possibility is to use official docker images for Microsoft SQL Server on Linux available here.
  • pytest - to run the tests.
  • pytest-timeout - for limiting long running tests.
  • psutil - for memory monitoring.
  • gevent (optional) - for async tests.
  • Sqlalchemy - (optional) - for basic Sqlalchemy testing.

To build documentation Sphinx and sphinx-rtd-theme are also needed.


In addition to the requirements above when developing pymssql on the Windows platform you will need these additional tools installed:

  • Visual Studio C++ Compiler Tools, see Python documentation for instructions on what components to install.
  • Cmake for building FreeTDS and win-iconv.
  • curl - for downloading FreeTDS and win-iconv.


If Windows computer is not readily available then virtual machine from Microsoft could be used.

Building pymssql wheel

It is recommended to use python virtual environment for building pymssql:

python3 -m venv <path_to_pve>

if using bash:

source <path_to_pve>/bin/activate

or if on Windows:


then install required python packages:

pip intall -U pip
pip install dev/requirements-dev.txt

If and now build wheel:

python3 bdist_wheel


pip wheel .

Environment Variables

By default links against OpenSSL if it is available, links FreeTDS statically and looks for FreeTDS headers and libraries in places standard for the OS, but there are several environment variables for build customization:

default - YES, defines if FreeTDS is linked statically or not.
default - YES, defines if pymssql is linked against OpenSSL.
if defined, determines prefix of the FreeTDS installation.
if defined, alows to fine tune where to search for FreeTDS headers.
if defined, alows to fine tune where to search for FreeTDS libraries.


PYMSSQL_FREETDS=/tmp/freetds python3 bdist_wheel

Building FreeTDS and pymssql from scratch

If one wants to use some specific FreeTDS version then there is a script dev/ that downloads and builds required FreeTDS version sources (and win-conv on Windows) and builds pymssql wheel. Run:

python dev/ --help

for supported options.




You will need to install two additional packages for testing:

easy_install pytest SQLAlchemy

You should build the package with:

python develop

You need to setup a tests.cfg file in tests/ with the correct DB connection information for your environment:

cp tests/tests.cfg.tpl tests/tests.cfg
vim|emacs|notepad tests/tests.cfg

To run the tests:

cd tests # optional

Which will go through and run all the tests with the settings from the DEFAULT section of tests.cfg.

To run with a different tests.cfg section:

py.test --pymssql-section=<secname>


py.test --pymssql-section=AllTestsWillRun

to avoid slow tests:

py.test -m "not slow"

to select specific tests to run:

py.test tests/
py.test tests/ tests/
py.test tests/
py.test tests/