Skip to main content

FreeTDS Quick Start

This is the first of a couple of follow-ups to my last post which covered how to install pyodbc on Ubuntu. The ultimate goal here is to be able to use Python (my new development weapon of choice) to communicate with SQL Server from GNU/Linux (specifically Ubuntu).

Part of this equation is to install FreeTDS, which is a set of C libraries that facilitate talking to SQL Server from Linux. I'm still wading through both pyodbc and pymssql but from what I can tell thus far both these solutions use (or can use) FreeTDS. (Random aside: if you're familiar with jTDS that's a Java implementation of FreeTDS. And another fun fact, TDS stands for "Tabular Data Stream," which is the protocol used by the native SQL Server client from Microsoft.)

Installing and using FreeTDS is simple enough but I figured I'd take notes for my own reference and share in case they help anyone else wanting to set this up.


If you're familiar with compiling and installing things from source on Linux there's nothing new here, and if you're not, this will show you just how easy this is.

First, download FreeTDS by clicking on the "stable release" link on the right-hand side of, extract the tar file, and in a terminal, navigate to the directory to which the files were extracted.

Next, type the following three commands, hitting enter after each one:
sudo make install

You'll see a ton of stuff being spit out to your terminal as you do this, but unless you see actual error messages that cause the execution of any of this to abort, that's all there is to it.

You can test the installation and get some information about the compile settings, etc. by typing this in a terminal:
tsql -C

With FreeTDS installed, now you just need to add some information to a configuration file to provide details about the servers and databases to which you wish to connect.


In your terminal, navigate to /usr/local/etc/ and in that directory you'll see the file freetds.conf Open that file in vim or your favorite text editor (note that you need to open the file using sudo).

The file contains some global settings and a couple of sample server entries, and you'll just be adding a new section to this config file.

At the bottom of the file add the following information, adjusting as appropriate with the connection information for your server and database.

    host =
    port = 1433
    tds version = 7.2

A few notes about these settings:

  • The [foo] in brackets at the top can be anything you want. That's simply an alias for these configuration settings, and we'll see how this is used in the "testing" section below.
  • The host is the host name or IP address of the server
  • The port is (obviously) the port number. By default SQL Server uses port 1433 but of course change accordingly if you're running on a non-standard port or using a named instance (which under the covers is just a port).
  • The tds version setting is specific to the version of SQL Server (or Sybase) to which you're connecting. Use 7.0 for SQL Server 7, 7.1 for SQL 2000, and 7.2 for SQL 2005 or 2008 (full details about TDS versions).

The FreeTDS docs have more details about the configuration file, including some additional settings you can include in the configuration file.


With your configuration file updated and saved, you can test your settings using the tsql utility that is installed as part of FreeTDS.

In a terminal enter the following:
tsql -S foo -U username -P password -D databasename

Notes about these flags and values:

  • The -S flag for the "server" is referring to the alias you created in the configuration file above.
  • -U is the user name and -P is the password for the database to which you wish to connect.
  • -D is the database name you wish to use after connecting to the server. If you don't provide a database name, it will connect to the default database for the user.

After you connect successfully you should see this prompt:

At that prompt you can enter and execute SQL statements against the database to which you connected.

More information about the tsql utility can be found on the "Confirm the install" page of the FreeTDS web site.

Errors and Troubleshooting

I personally didn't run into any issues in setting up FreeTDS that couldn't be chalked up to user error due to a lack of willingness to RTFM on my part.

That said, I just installed everything on a new machine this weekend and I do get an innocuous error after connecting to SQL Server:
Error 100 (severity 11):
    unrecognized msgno

At least I'm assuming it's innocuous since everything seems to be working, and unfortunately I couldn't find any additional information about this error (though admittedly I didn't hit up the mailing list yet).

Getting More Information

FreeTDS is an extremely well-documented project, so be sure and take advantage of the User Guide, which has a wealth of information about using FreeTDS in various programming languages, troubleshooting, advanced configuration, and more.

That's pretty much it for FreeTDS. Next time we'll bring pyodbc and pymssql back into the picture and start running some queries against SQL Server using Python.


xpou said…
set tds version to 8.0 in freetds.conf to fix the unrecognized msgno issue

tds version = 8.0
Anonymous said…
Excellent -- thanks for sharing.
NeMo said…
Sometimes doesn't work, the mirror is and in there you have to chose freetds-stable.tgz
NeMo said…
This comment has been removed by the author.
Brian said…
This was extremely helpful in getting me on my way. Thank you. I was able to get by on Debian 6 using apt-get and freetds packages.

ucanadvertise said…
Hi Matt, I was trying to set up FreeTDS with unixODBC. When I m trying to register FreeTDS with unixODBC I get the following error on running this command...

odbcinst -i -d -f tds.driver.template
odbcinst: SQLInstallDriverEx failed with Unable to find component name.

Can you please advice me in this regard.
NeMo said…
If you still getting that error, first you have to search the "" file, sometimes the route is not the default and sometimes there is not but

For example you could have something like this:

Description = ODBC for Microsoft SQL
Driver = /usr/lib/
UsageCount = 1
Threading = 2
NeMo said…
If you still getting that error, first you have to search the "" file, sometimes the route is not the default and sometimes there is not but

For example you could have something like this:

Description = ODBC for Microsoft SQL
Driver = /usr/lib/
UsageCount = 1
Threading = 2
Diego Jancic said…
Thanks, you are genius! After dealing with this for 2 days I installed it from source and it worked!
Matt Woodward said…
Great! Glad it was helpful.
Richard Majece said…
Cybersecurity means a lot for me in any case. I even found advices on when I had to learn more about android hacking.

Popular posts from this blog

Installing and Configuring NextPVR as a Replacement for Windows Media Center

If you follow me on Google+ you'll know I had a recent rant about Windows Media Center, which after running fine for about a year suddenly decided as of January 29 it was done downloading the program guide and by extension was therefore done recording any TV shows.

I'll spare you more ranting and simply say that none of the suggestions I got (which I appreciate!) worked, and rather than spending more time figuring out why, I decided to try something different.

NextPVR is an awesome free (as in beer, not as in freedom unfortunately ...) PVR application for Windows that with a little bit of tweaking handily replaced Windows Media Center. It can even download guide data, which is apparently something WMC no longer feels like doing.

Background I wound up going down this road in a rather circuitous way. My initial goal for the weekend project was to get Raspbmc running on one of my Raspberry Pis. The latest version of XBMC has PVR functionality so I was anxious to try that out as a …

Running a Django Application on Windows Server 2012 with IIS

This is a first for me since under normal circumstances we run all our Django applications on Linux with Nginx, but we're in the process of developing an application for another department and due to the requirements around this project, we'll be handing the code off to them to deploy. They don't have any experience with Linux or web servers other than IIS, so I recently took up the challenge of figuring out how to run Django applications on Windows Server 2012 with IIS.

Based on the dated or complete lack of information around this I'm assuming it's not something that's very common in the wild, so I thought I'd share what I came up with in case others need to do this.

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Assumptions and CaveatsThe operating system is Windows Server 2012 R2, 64-bit. If another variant of the operating system is being used, these instructions may not work properly.All of the soft…

Fixing DPI Scaling Issues in Skype for Business on Windows 10

My setup for my day job these days is a Surface Pro 4 and either an LG 34UC87M-B or a Dell P2715Q monitor, depending on where I'm working. This is a fantastic setup, but some applications have trouble dealing with the high pixel density and don't scale appropriately.
One case in point is Skype for Business. For some reason it scales correctly as I move between the Surface screen and the external monitor when I use the Dell, but on the LG monitor Skype is either massive on the external monitor, or tiny on the Surface screen.
After a big of digging around I came across a solution that worked for me, which is to change a setting in Skype's manifest file (who knew there was one?). On my machine the file is here: C:\Program Files\Microsoft Office\Office16\LYNC.EXE.MANIFEST
And the setting in question is this:
Which I changed to this: <dpiAware>False/PM</dpiAware>
Note that you'll probably have to edit the file as administr…