Installing Leo

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

These instructions look complicated because they’re long, but really they just boil down to:

  • install python. Python 3.9 or later is required.

  • run pip install leo from a python enabled command prompt.

  • run leo from that same python enabled command prompt.

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

Dependencies

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. rss.py will not function without feedparser. Etc.

Installing Leo with pip

Python’s pip tool will download and install Leo and all of Leo’s dependencies automatically.

  1. Install Python first, if necessary. Make sure to install Python 3, not Python 2.

  2. Check whether pip has been installed using the terminal window command below. If there’s an error Install pip:

    pip --version
    

In some circumstances using pip as a module works better:

python -m pip –version

  1. Download and install Leo and all required packages from PyPi:

    pip install leo
    

or

python -m pip install leo

PyPi install caveat

When Leo has been installed in non-editable mode* (the above) there will be messages in the log pane window when opening certain .leo files distributed with Leo, such as LeoDocs.leo. (_File >> Open Leo File >> …_). The warnings are not serious and may be ignored.

This is a known issue with no practical solution. Files in the root folder of the leo-editor code repository is not installed when using pip. This is because they need to be relative to ./leo-editor/leo folder, which make them at the top of PYTHONHOME/lib/site-packages, and thus in the global namespace and not part of leo as far as python is concerned.

Details at Missing files when installing Leo from PyPI using “pip install leo”.

* An editable install is from source code, either a git clone or downloaded archive. See:

  • An editable install is from source code, either a git clone or downloaded archive. See:

  • Installing Leo with git

  • Installing from sources (Windows)

Installing packages

Python: Leo will work on any platform that supports Python 3.9 or above. To install Python, see http://python.org.

PyQt: PyQt provides Leo’s widgets:

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

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

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.

Installing from sources (Windows)

Download Leo’s sources using one of the methods described at Leo’s download page.

After download unpack the zip archive where you like and from a python enabled command shell:

pip install –editable C:\path\to\leo-editor

This will leave Leo where it is and and create launch scripts in PYTHONHOME\Scripts.

Next see Running Leo and then optionally come back here for Creating Windows file associations.

Creating Windows file associations

From Settings menu select Open Desktop Integration. The new Leo file that opens will add 4 buttons under the menu bar:

[Register-leo] - Creates registry keys for Leo file type and .leo file association. Afterwards .leo files will show Leo icon and double-clicking them will open in Leo Editor.

[Unregister-leo] - Removes the above.

[add-desktop-links] - Creates launch shortcuts in desktop and system menu

[remove-desktop-links] - Removes the launch shortcuts

Installing Leo from sources (all platforms)

Generic recipe for all platforms. Adjustment for local norms is expected. For example 7z could be unzip or interactive extraction and wget could be a browser download.

Linux: it’s generally advised to use pip --user flag instead of sudo.

Assumes Python 3.9 or later is installed and in PATH.

Installing from source code into a new environment must be done in discrete steps: download, unpack archive, and install as editable mode.

Example:

wget https://github.com/leo-editor/leo-editor/archive/devel.zip
7z x devel.zip -o C:\apps
pip install --editable C:\apps\leo-editor-devel

For easier upgrading substitute git clone for wget & 7z steps:

git clone --no-single-branch -b devel --depth=200 https://github.com/leo-editor/leo-editor.git
pip install --editable leo-editor

time passes, upgrade desired:

pushd c:\apps\leo-editor
git pull
pip uninstall leo
pip install --editable .

b and depth are optional, but will dramatically speed up download time as it only grabs the latest development branch, the tips of other branches, and skips all but the last couple weeks or months of history.

Note

Direct pip install https://github.com/leo-editor/leo-editor/archive/devel.zip does not work. For proper operation Leo relies on presence of certain files outside of the standard Python site-packages folder structure.

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

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 http://git-scm.com/.

  2. Get Leo from GitHub by doing:

    git clone --depth=500 --no-single-branch https://github.com/leo-editor/leo-editor (http access)

    or:

    git clone --depth=500  --no-single-branch git@github.com:leo-editor/leo-editor.git (ssh access)

    followed by checking out the _devel_ branch:

git checkout devel

  1. Install dependencies and create leo script launcher:

    pip install --editable path/to/leo-editor
    

And that’s it! You can run leo with PYTHONHOME/Scripts/leo or python leo-editor/launchLeo.py. When you want to refresh the code with latest modifications from GitHub, run git pull.

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 (mxcl.github.com/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 http://brew.sh/.

  • 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. See the instructions at https://brew.sh/.

  • 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 Leo-4.9-final-a.zip, unzipped it, and ran “python launchLeo.py” 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.

Installing everything with Anaconda or Miniconda

The Anaconda scientific computing environment includes Python, NumPy, SciPy, PyQt, and over a thousand other tools, packages and libraries. It’s a 500+ MB download but you’re guaranteed to have everything needed.

The Miniconda environment includes just Python and the conda package management tool. Pick and choose from the full Anaconda ecosystem.

Preparation, create an environment for Leo, activate it, and then install python:

conda create -n leo
conda activate leo
conda install python

Strictly speaking this step can be skipped and Leo installed in the conda _base_ environment. The conda developers generally advise against installing in _base_ unless this program is the only thing the machine will be used for.

To install Leo run this from a console:

pip install leo