next up previous
Next: Upgrading from a previous Up: IPython An enhanced Interactive Previous: Overview

Subsections


Installation

Please see the notes in sec. 3 for upgrading IPython versions.

Under Unix-type operating systems (Linux, Mac OS X, etc.)

  1. Unzip/untar the IPython-XXX.tar.gz file wherever you want (XXX is the version number). It will make a directory called IPython-XXX. Change into that directory where you will find the files README and setup.py. Once you've completed the installation, you can safely remove this directory.
  2. If you are installing over a previous installation of version 0.2.0 or earlier, first remove your $HOME/.ipython directory, since the configuration file format has changed somewhat (the '=' were removed from all option specifications). Or you can call ipython with the -upgrade option and it will do this automatically for you.
  3. IPython uses distutils, so you can install it simply by typing at the system prompt (don't type the $)
    $ python setup.py install
    Note that this assumes you have root access to your machine. If you don't have root access or don't want IPython to go in the default python directories, you'll need to use the -home option. For example:
    $ python setup.py install -home=$HOME/local
    will install IPython into $HOME/local and its subdirectories (creating them if necessary).
    You can type
    $ python setup.py -help
    for more details.
Note that when installing, you will see some SyntaxError messages go by rapidly. Please ignore them, they are completely harmless (the result of an ugly but necessary hack around some limitations of distutils).

RedHat 7.x notes

RedHat made the 'wise' choice of using Python 1.5.2 as the default standard even for users (not just for internal system stuff). Since they couldn't be bothered to make things right, now you need to manually play around to get things to work with Python 2.x (which IPython requires).

First, your system administrator may have fixed things so that as a user you automagically see python 2.x. Test this by typing 'python' at the prompt. If you get a Python 2.x prompt, you're safe. Otherwise you'll need to explicitly call Python2.

Start by making sure you did install Python 2.x. The rpm for it is named python2....rpm. You can check by typing 'python2' at the command prompt and seeing if you get a python prompt with 2.x as the version. If you don't have it, install the Python 2.x rpm now.

Once you have confirmed you have Python 2.x installed, call the IPython setup routine as
$ python2 setup.py install

Hopefully, things will work. If they don't, go yell at RedHat, not me.

Under Windows

Please note that for the automatic installer to work you need Mark Hammond's PythonWin extensions (and they're great for anything Windows-related anyway, so you might as well get them). If you don't have them, get them at:

http://starship.python.net/crew/mhammond/

From the download directory grab the IPython-XXX.zip file (but the popular WinZip handles .tar.gz files perfectly, so use that if you have WinZip and want a smaller download).

Unzip it and double-click on the setup.py file. A text console should open and proceed to install IPython in your system. If all goes well, that's all you need to do. You should now have an IPython entry in your Start Menu with links to IPython and the manuals.

If you don't have PythonWin, you can:

These steps are basically what the auto-installer does for you.

IPython tries to install the configuration information in a directory named .ipython located in your 'home' directory, which it determines by joining the environment variables HOMEDRIVE and HOMEPATH. This typically gives something like C:\Documents and Settings\YourUserName, but your local details may vary. In this directory you will find all the files that configure IPython's defaults, and you can put there your profiles and extensions. This directory is automatically added by IPython to sys.path, so anything you place there can be found by import statements.


Help access

This is true for Python 2.1 in general (not just for IPython): you should have an environment variable called PYTHONDOCS pointing to the directory where your Python documentation lives. In my system it's /usr/share/doc/python-docs-2.1.1, check your local details or ask your systems administrator.

You really want to set this variable correctly so that Python's pydoc-based help system works (it's very powerful).

Under Windows it seems that pydoc finds the documentation automatically, so no extra setup appears necessary.

Initial configuration comments

All of ipython's configuration information, history, logs, is stored in a directory named by default $HOME/.ipython. You can change this by defining the environment variable IPYTHONDIR, or at runtime with the command line option -ipythondir.

If all goes well, the first time you run IPython it should automatically create a user copy of the config directory for you. Go poking around in there to learn more about configuring the system. As we said, this copy by default will be called $HOME/.ipython

If there is a problem, these are the instructions for manual installation:

  1. mkdir $HOME/.ipython
  2. Copy all the files in IPython/UserConfig to $HOME/.ipython/, except for the files named __init__*
  3. In $HOME/.ipython, rename all the ipythonrc*.py files by removing the .py extension. They aren't really Python files, this is a workaround for a distutils limitation, and normally is done for you by the auto-installer.
Information on how to further customize the ipythonrc* files and how to build a hierarchy of them to manage IPython 'profiles' is provided in the sample files.

The default configuration has most bells and whistles turned on (they're pretty safe). But there's one that may cause problems on some systems: colored prompts and exception handlers.

If when you start IPython the input prompt shows garbage like:
[0;32mIn [[1;32m1[0;32m]: [0;00m
instead of
In [1]:
this means that your terminal doesn't properly handle color escape sequences.

You can either try using a different terminal emulator program or switching coloring off completely. To do the latter, edit the file $HOME/.ipython/ipythonrc and set the colors option to the value 'NoColor' (without quotes).

Terminals that seem to handle the color sequences fine:

Terminals with problems:

Currently available color schemes for prompts and exceptions:

In the future, more schemes may be implemented (if you add one, send it in. They are easy to write, look at the code in ultraTB.py and Prompts.py).


(X)Emacs users

To the best of my knowledge, the comments below apply both to GNU Emacs and to XEmacs2.

In X/Emacs we get the following types of terminals (as returned by os.environ['TERM']):

Color support

All of these terminal types will support coloring of prompts and tracebacks, even though only light versions of colors seem to be displayed. I may write an Emacs-specific color scheme in the future (contributions welcome, look at ultraTB.py for details). But for this color support to work properly, you must first copy the following lines to your .emacs file:

; Customizations for IPython

(defun activate-ansi-colors () 
  (require 'ansi-color) 
  (ansi-color-for-comint-mode-on))

(add-hook 'comint-mode-hook 'activate-ansi-colors)

(add-hook 'shell-mode-hook 'activate-ansi-colors)

; Set IPython to be the python command and give it arguments

(setq py-python-command "ipython")

(setq py-python-command-args 
      (cond 
       ((eq frame-background-mode 'dark) 
        '("-colors" "Linux")) 
       ((eq frame-background-mode 'light) 
        '("-colors" "LightBG")) 
       (t  ; default (backg-mode isn't always set by XEmacs) 
        '("-colors" "LightBG")) 
       ) )

You can customize the above to suit your personal preferences.

Name completion

'eterm' buffers support TAB name completion like a normal terminal, but 'emacs' and 'dumb' ones do not support it well, because Emacs itself takes control of line input. You will thus lose full name completion in an IPython buffer started via C-c !. All other features of IPython will work normally.

Still, name completion works to some extent: the completions are not printed when you hit TAB, instead you must hit Return after TAB (giving a SyntaxError, of course). At this point you get a printout of the possible completions and you can get your previous line with Ctrl-UpArrow. Not perfect, but better than nothing.

I know it's clumsy, but so far efforts to fix this have failed. Any Emacs gurus out there who can think of a clean way to fix this are encouraged to contact the developers at the addresses given in sec. 14. The issue (I think) boils down to the following: Emacs only prints the contents of a command received by its sub-process in a comint buffer when it gets an EOL (or more precisely, the result of comint-send-input). At that point it prints out all the buffered contents from the subprocess. But for normal TAB completion to work, one needs to print the list of completions at the current cursor position (possibly completing part of the line) before the command is finished. So a kind of catch-22 situation arises. As I said, all ideas/fixes are welcome from the Emacs gurus out there.


next up previous
Next: Upgrading from a previous Up: IPython An enhanced Interactive Previous: Overview
Fernando Perez 2002-04-29