Getting IPython readline and auto-completion to work on Mac OS X

It's taken me some time and a lot of web pages which tried to solve the readline support with all kinds of hacks, but finally I've been able to get readline support and auto-completion for IPython to work. As it can be quite confusing and hard to follow all posts, this will be a step-by-step approach to get things to work. Note that I've got it working on Mac OS X 10.5.7 Leopard. It is expected to work on Leopard at least. Other versions might not require the exact same solution.

If you don't already have IPython you can install it by opening a console and typing

sudo easy_install ipython

Mac OS X does include a readline functionality, but not 'the real one' gnureadline, because of a license issue. It can be manually installed, which we will do next. If you've not done so already, open a console and type

sudo easy_install -f http://ipython.scipy.org/dist/ readline

Type in your password and the readline functionality will be installed. Big joy you would think, but it's very well possible that it still doesn't work. Try for yourself by typing the following in your console:

ipython

IPython will start. Let's see if we can auto-complete here. First type

  1. import sys

Now we've done an import and we will try to have auto-complete hint what we can do with it. In the next line type

  1. sys.

Press Tab directly after the dot. If IPython hints all types of functions preceded by sys. in a list, you're done with this tutorial. If your cursor just jumps, auto-complete doesn't work and you might want to execute the following steps.
IPython has a file which is used to start it. We need to edit this file to tell where the readline module is installed.
If you're still in IPython, close it by pressing CTRL+D and confirming (y). You are now back on the console again.
The file which we are about to edit (done with Vim here) is a read-only file, so we need to sudo once again. Type the following

sudo vim /usr/local/bin/ipython

Enter your password and Vim will open a config file with just a few lines like

  1. #!/System/Library/Frameworks/Python.framework/Versions/2.5/Resources/Python.app/Contents/MacOS/Python
  2. # EASY-INSTALL-ENTRY-SCRIPT: 'ipython==0.9.1','console_scripts','ipython'
  3. __requires__ = 'ipython==0.9.1'
  4. import sys
  5. from pkg_resources import load_entry_point
  6.  
  7. sys.exit(
  8. load_entry_point('ipython==0.9.1', 'console_scripts', 'ipython')()
  9. )

First find the location of the egg directory of readline which you've just installed. It's probably something like /Library/Python/site-packages/readline-.egg
I've installed the i386 readline module version 2.5.1, so my location is /Library/Python/2.5/site-packages/readline-2.5.1-py2.5-macosx-10.5-i386.egg
We will need this location next.
Go back to your console where the file is still opened.
Leave the first two lines and the import sys line. The rest can be commented out.
Now insert the following three lines after import sys:

  1. sys.path.insert(0, 'path to readline egg')
  2. import IPython.Shell
  3. IPython.Shell.start().mainloop()

In my case, the ipython file looks as follows:

  1. #!/System/Library/Frameworks/Python.framework/Versions/2.5/Resources/Python.app/Contents/MacOS/Python
  2. # EASY-INSTALL-ENTRY-SCRIPT: 'ipython==0.9.1','console_scripts','ipython'
  3. #__requires__ = 'ipython==0.9.1'
  4. import sys
  5. #from pkg_resources import load_entry_point
  6.  
  7. sys.path.insert(0, '/Library/Python/2.5/site-packages/readline-2.5.1-py2.5-macosx-10.5-i386.egg')
  8.  
  9. import IPython.Shell
  10. IPython.Shell.start().mainloop()
  11.  
  12. #sys.exit(
  13. # load_entry_point('ipython==0.9.1', 'console_scripts', 'ipython')()
  14. #)

Save and quit the file by typing

  1. :wq

You're back at the command line again. Let's test the auto-complete. Again type

ipython

IPython will start. Let's see if we can auto-complete here. First type

  1. import sys

Now we've done an import and we will try to have auto-complete hint what we can do with it. In the next line type

  1. sys.

Press Tab directly after the dot. If all went well Python hints all types of functions preceded by sys. in a list.

Sites that helped me and / or might be useful for you:

Be Sociable, Share!

9 comments

  1. sbgskl says:

    Tried this on OS X 10.6 Snow Leopard – does not seem to work.

  2. fizzy33 says:

    worked for me on OS X except “import sys.” followed by a tab didn’t show anything but a bell. I had to “from sys import” then tab and I got
    In [7]: from sys import
    __egginsert copyright getcheckinterval meta_path setrecursionlimit

    etc,etc

  3. DeadParrot55 says:

    Fantastic! This was by far the easiest solution I’ve found, and it seemed to work perfectly on 10.6.

  4. ElJeffe says:

    Excellent! worked like a charm!

  5. notbob says:

    Works well for me.

  6. insanelygreat says:

    Great tutorial. It finally made ipython useable on Snow Leopard.

  7. Gripp says:

    lipo: can’t open input file: /var/tmp//ccDCFmvP.out (No such file or directory)
    error: Setup script exited with error: command ‘gcc-4.2′ failed with exit status 1

    :(

  8. D.Q. says:

    easier yet:
    download readline-***.egg from pypi (googles)
    sudo easy_install readline-***.egg
    done

  9. dahntheboss says:

    for IPython 0.13:

    replace

    import IPython.Shell
    IPython.Shell.start().mainloop()

    with

    import IPython
    IPython.embed()

Leave a Reply

Your email address will not be published. Required fields are marked *


seven − = 5