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
Matt Woodward 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.

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 …

Setting Up Django On a Raspberry Pi

This past weekend I finally got a chance to set up one of my two Raspberry Pis to use as a Django server so I thought I'd share the steps I went through both to save someone else attempting to do this some time as well as get any feedback in case there are different/better ways to do any of this.

I'm running this from my house (URL forthcoming once I get the real Django app finalized and put on the Raspberry Pi) using I don't cover that aspect of things in this post but I'm happy to write that up as well if people are interested.

General Comments and Assumptions

Using latest Raspbian “wheezy” distro as of 1/19/2013 (’lll be using Nginx ( as the web server/proxy and Gunicorn ( as the WSGI serverI used heavily as I was creating this, so many thanks to the author of that tutorial. If you’re looking for more details on …

The Definitive Guide to CouchDB Authentication and Security

With a bold title like that I suppose I should clarify a bit. I finally got frustrated enough with all the disparate and seemingly incomplete information on this topic to want to gather everything I know about this topic into a single place, both so I have it for my own reference but also in the hopes that it will help others.Since CouchDB is just an HTTP resource and can be secured at that level along the same lines as you'd secure any HTTP resource, I should also point out that I will not be covering things like putting a proxy in front of CouchDB, using SSL with CouchDB, or anything along those lines. This post is strictly limited to how authentication and security work within CouchDB itself.CouchDB security is powerful and granular but frankly it's also a bit quirky and counterintuitive. What I'm outlining here is my understanding of all of this after taking several runs at it, reading everything I could find on the Internet (yes, the whole Internet!), and a great deal…