The open source Qt development toolkit is a popular choice for cross-platform development. It provides native-looking widgets and tight integration with the underlying platform on Windows, Linux, and Mac OS X. Qt applications that are written in C++ are easy to compile and deploy across all three platforms, but what if you don't like C++? I prefer Python, a dynamic programming language with a richly expressive syntax and exceptionally powerful support for introspection.

Fortunately, there are cross-platform Python bindings for Qt. The downside, however, is that packaging PyQt applications so that they can be deployed to users on Windows and Mac OS X is an immensely frustrating and arcane process. I declared victory last week after spending several hours battling with MacPorts and distutils. Now that I have unlocked the toolkit's dark mysteries, I can show you the hidden secrets that will allow you to achieve mastery of the alchemical art of cross-platform PyQt application deployment.

First, you'll need access to each platform for which you want to build redistributable packages. The easiest way to accomplish this is to use a Mac and either triple-boot or virtualize Windows and Linux. The initial setup process for Mac OS X will require a lot of very heavy compilation, so you are going to be in for a world of pain and a very long wait if you try to do this on a Mac mini.

My test application

My computing environment is a quad core Mac Pro configured to dual-boot OS X and openSUSE 11.1. For Windows, I'm running XP in VirtualBox. I do most of my actual development in Linux, but you can do it pretty comfortably on any of the platforms.

My test application, which I call Orbital Liftr, is a simple utility that I made for batch uploading graphics to Ars Technica's content management system. The Ars CMS is built on Movable Type, which means that it supports the MetaWeblog XML-RPC API, and my app lets you upload images to any standard Movable Type or WordPress blog that supports the API. The app has a few simple features like support for receiving images via drag-and-drop, and it can proportionally resize them before uploading.

The program consists of one module of Python code which contains the application logic and a few basic user interface forms that I made with the Qt Designer program. I have published the complete source code of the program on Launchpad. You can use it to follow along with this tutorial, or you can use your own code.

PyQt on Windows

To build a distributable PyQt package for Windows, you first need to set up a working PyQt execution environment. Start by downloading and installing the standard Qt SDK from the Qt Software website. Next, you will need to install Python 2.6.1. Use the binary installer for Windows from the Python website.

The next step is installing the Python bindings, which can be obtained from the download page at the PyQt website. You'll want to get the Windows installer that is compatible with Python 2.6; it's listed at the bottom of the Binary Packages section.

These components should be enough to give you a fully functional environment for running PyQt applications. You can test it by making a simple PyQt application with a few widgets in a single .pyw file. If your PyQt environment installed correctly, you should be able to run the program by double-clicking the .pyw file in the file manager. There are several example scripts that come bundled with the PyQt installation. These can be found in the site-packagesPyQt4examples folder.

Now that you have a working PyQt environment, you need to package up the application so that you can distribute it to users and make it possible for them to run it without having to install all of the dependencies. This is done with a utility called py2exe that leverages Python's distutils framework. An installer for py2exe is available from the SourceForge website.

You will need to adapt your setup.py script so that it can provide proper instructions to py2exe. If your program is simple and you already know how to use distutils, this shouldn't be terribly hard. The following example shows my setup.py file:

from distutils.core import setup import py2exe setup(name="liftr", version="0.1", author="Ryan Paul", author_email="segphault@arstechnica.com", url="https://launchpad.net/liftr", license="GNU General Public License (GPL)", packages=['liftr'], package_data={"liftr": ["ui/*"]}, scripts=["bin/liftr"], windows=[{"script": "bin/liftr"}], options={"py2exe": {"skip_archive": True, "includes": ["sip"]}})

Most of that is pretty much standard distutils. The last two lines were added to accommodate py2exe. The "windows" parameter specifies the script that py2exe should use to launch the actual program. As you can see, for a simple program that is being ported from Linux, it's the same thing that you already have in your "scripts" parameter.

The "options" parameter allows you to pass specific instructions to py2exe. For PyQt applications, you will need to tell it to include sip, a fundamental component of the PyQt binding system.

The py2exe tool will typically compress all of your required Python library modules into a single zip file in order to reduce space and keep your redistributable package clean. I disable that with the skip_archive option. My program dynamically loads the user interface description XML files at runtime, but it can't read those files when they are bundled up in the zip archive.

When you are building PyQt applications with py2exe, you need to either statically generate your user interface modules from the XML description files in advance, disable archiving with the skip_archive option, or structure your program so that the UI files will not end up in the archive.

After you finish making your setup.py script, you can build your redistributable package by running it from the command line:

$ python setup.py py2exe

The terminal will display a lot of messages as it byte-compiles your modules and copies all of the necessary dll files and other dependency components. The automated setup process will take place in the "build" directory and everything that your users need will be copied into the "dist" directory. If the script won't execute, make sure that Python is in your PATH environment variable.

To deploy your application to users, ship them everything that is in the "dist" directory. This adds up to roughly 25 MB for a simple program. It includes the executable and all of the runtime dependencies, which means that users will be able to run the program without having to install the other components.

You can just zip it up and ship it out that way, but it will be more convenient for your users if you give them a single self-standing executable with a standard installer wizard. A lot of PyQt developers seem to like Inno Setup, a free installer maker.

Although your users will not have to manually install Qt or the PyQt bindings, they might still have to install the VC++ 2008 Redistributable Package. This package is available directly from Microsoft.

Deploying PyQt on Windows works reasonably well. Inno Setup uses good compression, so you can get your final package down to an acceptable size and make it easy for users to install. The biggest challenge is getting py2exe to deal appropriately with certain kinds of corner cases.

If your application is complex or structured in an unusual way, you might run into problems. For example, py2exe doesn't respect the distutils package_data option. There are a few workarounds for problems of that nature, and you can get more details about py2exe from the project's website.