Installing Leo

This chapter tells how to install and run Leo on Windows, Linux and MacOS.

Important: If you have any problems installing Leo, please ask for help on Leo’s help forum.


Leo’s minimal dependencies are:

The following packages are optional, but recommended:

  • Docutils: required for the rst3 command and the viewrendered plugins.
  • Sphinx: required to regenerate Leo’s documentation.
  • PyEnchant: required for spell checking.

Plugins may require other packages. For example, viewrendered requires Markdown if one wishes to use markdown rendering, but it is optional. will not function without feedparser. Etc.

Installing packages

Python: Leo will work on any platform that supports Python 2.6 or above, including Python 3.0 and above. To install Python, see

PyQt: PyQt provides Leo’s widgets.

Important: The PyQt version must match your installed Python version. Remember that Leo requires Python 2.6 or later, or Python 3.0 or later.

PyEnchant: You must install PyEnchant if you want to use Leo’s Spell tab.

There is an executable installer for Windows users.

Installing Leo itself

Installing Leo on Windows

Install Python and Qt, as described above (Installing Packages).

Now you have a choice. You can use Leo’s binary (single-click) installer or download Leo’s sources directly.

Using the single-click installer

Leo has a binary installer for Windows, available at the SourceForge download page. The binary installer installs Leo and sets Windows file associations. Now see Running Leo for how to run Leo after installing it.

Installing from sources (Windows)

You may download Leo’s sources in one of three ways, as described at Leo’s download page. If the sources are zipped, unpack them into a temp folder. You may place the sources anywhere you like, including Python’s *site-packages* folder, for example, C:\Python26\Lib\site-packages.

Next, you will find it convenient to create Windows files associations for .leo files, as described in the next section.

Creating Windows file associations

Important: Leo’s binary Windows installer sets file associations automatically, so this section is needed only if you are installing Leo from a .zip file or other sources.

There are two ways of associating .leo files with Leo. The first uses the Windows control panel, the second, the Windows console.

Method 1: Using the Windows Control Panel

The goal is that you want to associate .leo files with the following command:

"<path to python>\python.exe" "<path to>\" "%1"

Before Windows 7, you do this with using the Folder Options control panel. In Windows 7, you do this with the Default Programs control panel.

Note: “%1” passes just the file being clicked on, quoted for spaces etc. The quotation marks are needed to handle file paths containing spaces.

Warning: In a batch file, %1 passes just the first command line parameter. It is logical to expect %* to work for file associations just as in batch files. Alas, it does not.

Method 2: Using the Windows Console

Open a Windows console with administrator privileges, then type:

ftype LeoFile="<path to python>\pythonw.exe" "<path to>\" "%1" %*
assoc .leo=LeoFile

And put this leo.bat in %PATH%:

@start /b "Leo" "<path to python>\python.exe" "<path to>\" %*

You may omit the /b option if you want to create a separate console window for Leo.

Installing Leo with git

Important: This section tells how to set up git so that you can grab the latest sources using git clone.

Many users will want to track the development version of Leo, in order to stay on top of the latest features and bug fixes. Running the development version is quite safe and easy, and it’s also a requirement if you want to contribute to Leo.

  1. First, you need to get git from

  2. Get Leo from GitHub by doing:

    git clone (http access)


    git clone (ssh access)

And that’s it! You can run leo/core/ directly. When you want to refresh the code with latest modifications from GitHub, run git pull.

Installing Leo on Linux

If you are using Debian/Ubuntu, it’s best to install Leo from a debian package, as described next. This provides file associations, icons, launcher items, etc.

Otherwise, you may install Leo from sources.

Installing from a debian package

Add these files to /etc/apt/sources.list:

deb jaunty main
deb-src jaunty main

Then run:

sudo apt-get update
sudo apt-get install leo

Installing from sources (Linux)

You may download Leo’s sources in one of three ways, as described at: If the sources are zipped, unzip them into a folder in your home directory, say ~/leo-5.5.

You now have several choices.

  1. You can run Leo from your home directory. Just add ~/leo-5.5 to your path.

  2. You can install leo into /usr/local/lib and /usr/local/bin with:

    cd ~/leo-5.5 sudo python install

See Running Leo for how to run Leo after installing it.

Installing Leo on MacOs 10.7 (Lion) and later

Many thanks to Ludwig Schwardt for the following installation instructions. Using the HomeBrew installation method is much easier than before.

Note from EKR: When upgrading MacOS, it’s probably a good idea to uninstall pyqt, sip and qt first:

brew remove pyqt sip qt
brew install qt sip pyqt

I (Ludwig) recently received a new MacBook Pro and did a fresh upgrade to Mac OS 10.7 (Lion). I then used the opportunity to test out installation procedures of various software on a clean system. My main finding is that the excellent Homebrew ( makes things much easier these days.

Why Homebrew? It does not try to replace every single bit of functionality on your Mac with their own version, like Macports or fink. It reuses the existing libraries as far as possible. No need to reinstall Python, for example (one of my pet gripes when people try to install new software on their Macs, and the source of much confusion and pain). It installs to /usr/local, the standard place to find third-party libraries and headers, instead of the obscure /opt or /sw. It’s simple to use and to extend.

Here is my installation write-up:

  • Read the Homebrew installation instructions at

  • Make sure you have Xcode installed (test it by confirming that “gcc” runs in the Terminal). Only the smaller command-line tools are required; there is no need to get the full Xcode beast.

  • In preparation for Homebrew, the best option in my opinion is to delete /usr/local via:

    sudo rm -rf /usr/local

    and install any software in it via HomeBrew instead.

    The HomeBrew package manager is so easy to use that you will find replacing deleted packages a snap.

    If deleting /usr/local fills you with dread (you do not want to lose your beloved third-party software), the second-best option is to make sure you have write permission for the directory via:

    sudo chown -R <your user name>:admin /usr/local

    If you don’t know your username, run “whoami”. :-) This is useful because homebrew actually discourages you from installing third-party software as the superuser (the usual Mac apps in /Applications are also installed as the normal user, for that matter).

  • Install Homebrew ( by running the following command in the Terminal:

    ruby -e "$(curl -fsSL"
  • Run “brew doctor” and check any further suggestions to improve your system.

    EKR note: I thought I had installed command-line tools after installing the XCode page. I hadn’t, and “brew doctor” told me so.

  • Run “brew update” to get the latest formulas

  • Install sip and note the caveat:

    brew install sip

    This warns you to add the local python directory to your PYTHONPATH. Make a note of what this is (especially if you are not on Lion!).

  • Add the following lines to your ~/.bash_profile (or ~/.profile on Leopard). This is the default for LION:

    export PATH=/usr/local/bin:$PATH
    # This is for SIP (and PyQt) as suggested by Homebrew
    export PYTHONPATH=/usr/local/lib/python2.7/site-packages:$PYTHONPATH
  • Install PyQt:

    brew install pyqt
  • Open a new Terminal tab / window so that the above settings take effect, and install Leo. I downloaded the, unzipped it, and ran “python” inside the Leo directory.

It would really be great to get a Leo formula going for Homebrew. As mentioned before, the main question is just where to place all the Leo files in the /usr/local hierarchy.