Get in touch


Distribute Django Web Apps as Native Desktop Apps

Part 1: General notes and setup of development environment

Final Django App

A couple of months ago I worked on a project for which I needed to install an Open Source web app written in Django I first installed a couple of years ago. I was surprised to see that the setup of the app on an OS X machine was still complex, though from my perspective a double-clickable application would be desirable.

I thought it might be great if someone could package the whole Django app into a neat little app bundle, which can be distributed as a simple downloadable application which can be double-clicked to start the app.

Furthermore, I thought that I needed a single UI kit to build web applications as well as apps running on the Desktop.

This article is about packaging your own Python web app as a double-clickable app including an OS native browser loading your web app, which can be built for OS X, Linux and Windows (though the code examples below are for OS X only).

If you attended MacDevOps:YVR in Vancouver in June 2016, you can use this article to build the example apps I used in my talk and the workshop. Here you find the HTML version of my presentation and here is the workshop video.


The idea is to use a single UI kit for both web and local apps and to run Python as its backend, as this allows reusing your code if you run your app in different environments. As I build web apps it was clear I needed HTML, CSS and a bit of JavaScript for my frontend, while a full-stack web framework like Django would be a great helper, too. (Though the following text works with pure CherryPy web sites, too.)

There are some descriptions on the net, which explain how to package Django and CherryPy applications using py2app, and they make deployment quite easy. Yet, they don't bundle their own web browser with their apps, and I think this can be a requirement for some applications.

After some thinking I decided I wanted to achieve the following:

Technology used in this article

After some investigation I decided I wanted to use the following technology:

All the tools above work with both Python 2.7 and Python 3.x, which gives you enough flexibility for your project.

If you are not a Python developer, there are other tools like MacGap, Electron and NW.js, which are more targeted at JavaScript developers. If you read this though, I guess you are at least interested in using Python.

Prepare your development environment

In the following example we are using Python 3.4 on an OS X 10.11.5 machine. You can use another Python version, but please be warned that the build process will probably require a slightly different setup.

Please make sure you have the latest Xcode installed, which you can download for free from the Apple App Store. At the time of this writing, version 7.3.1 is the latest version. Please install Xcode's command-line utilities by opening the Terminal and typing:

sudo xcode-select --install

If this is the first time you run Xcode you need to accept the license agreement first.

Once Python 3.4 and Xcode are installed, navigate to a place in your filesystem, where you want to create your project. We use ~/Documents/PyBrowse as our starting point. Open a Terminal and create the folder:

cd ~/Documents mkdir PyBrowse cd PyBrowse

Now we need to set up a virtual Python environment. To do that, make sure you have virtualenv installed. If

which virtualenv

does not output something like '/usr/local/bin/virtualenv', then you need to install it:

pip3.4 install virtualenv

We use 'pip3.4' as we have installed this pip version with our Python 3.4 installation. Please adapt this to your environment if you use any other Python setup. Then cd into our new working directory and type

virtualenv -p /Library/Frameworks/Python.framework/Versions/3.4/bin/python3.4 env

This will copy Python 3.4 including pip into a directory named 'env' inside your current working directory. To activate this Python version, type

source env/bin/activate

Whenever you want to work on your project, you need to activate this Python environment. Once you want to deactivate this virtual Python environment, type 'deactivate' in the Terminal.

Install pywebview:

pip install pywebview

The latter can take a little while as pywebview requires PyObjC on the Mac and will install pyobjc-core and pyobjc as dependencies. Make sure that there is no directory named "build" in your current working directory, and if the pyobjc installation takes longer than a couple of minutes, hit CTRL-C to cancel the installation and then type

pip install pyobjc-core pip install pyobjc pip install pywebview

instead. Read more about this at

If you type 'pip freeze' you will see all the modules your virtual Python environment includes. Please note, that py2app has been installed, too.

A word on IDEs

To write the following code, you can use any text editor which deals properly with line breaks, like TextWrangler, BBedit, Sublime Text, vi, nano, to name a few. If you work on more complex projects, from my perspective an integrated development environment like PyCharm makes your life much easier. The choice of course is up to you.

Now our development environment has been set up and we write our first application.

Part 2: Build a browser and bundle it as an app