Subsections

- Access to the Python help system
- Editor
- Color
  - Input/Output prompts and exception tracebacks
  - Object details (types, docstrings, source code, etc.)
- (X)Emacs configuration
  - Notes

#
Initial configuration of your environment

This section will help you set various things in your environment for your IPython sessions to be as efficient as possible. All of IPython's configuration information, along with several example files, 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, based on its builtin defaults. You can look at the files it creates to learn more about configuring the system. The main file you will modify to configure IPython's behavior is called `ipythonrc` (with a `.ini` extension under Windows), included for reference in Sec. 7.1. This file is very commented and has many variables you can change to suit your taste, you can find more details in Sec. 7. Here we discuss the basic things you will want to make sure things are working properly from the beginning.

##
Access to the Python help system

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

This is the directory which holds the HTML version of the Python manuals. Unfortunately it seems that different Linux distributions package these files differently, so you may have to look around a bit. Below I show the contents of this directory on my system for reference:

`[html]> ls`
`about.dat acks.html dist/ ext/ index.html lib/ modindex.html stdabout.dat tut/ about.html api/ doc/ icons/ inst/ mac/ ref/ style.css`

You should really make sure this variable is correctly set so that Python's pydoc-based help system works. It is a powerful and convenient system with full access to the Python manuals and all modules accessible to you.

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

## Editor

The `%edit` command (and its alias `%ed`) will invoke the editor set in your environment as `EDITOR`. If this variable is not set, it will default to `vi` under Linux/Unix and to `notepad` under Windows. You may want to set this variable properly and to a lightweight editor which doesn't take too long to start (that is, something other than a new instance of `Emacs`). This way you can edit multi-line code quickly and with the power of a real editor right inside IPython.

If you are a dedicated `Emacs` user, you should set up the `Emacs` server so that new requests are handled by the original process. This means that almost no time is spent in handling the request (assuming an `Emacs` process is already running). For this to work, you need to set your `EDITOR` environment variable to `'emacsclient'`. The code below, supplied by Francois Pinard, can then be used in your `.emacs` file to enable the server:

`(defvar server-buffer-clients)`
`(when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))`
`(server-start)`
`(defun fp-kill-server-with-buffer-routine ()`
`(and server-buffer-clients (server-done)))`
`(add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))`

You can also set the value of this editor via the commmand-line option '-`editor'` or in your `ipythonrc` file. This is useful if you wish to use specifically for IPython an editor different from your typical default (and for Windows users who tend to use fewer environment variables).

## Color

The default IPython configuration has most bells and whistles turned on (they're pretty safe). But there's one that may cause problems on some systems: the use of color on screen for displaying information. This is very useful, since IPython can show prompts and exception tracebacks with various colors, display syntax-highlighted source code, and in general make it easier to visually parse information.

The following terminals seem to handle the color sequences fine:

- Linux main text console, KDE Konsole, Gnome Terminal, E-term, rxvt, xterm.
- CDE terminal (tested under Solaris). This one boldfaces light colors.
- (X)Emacs buffers. See sec.3.4 for more details on using IPython with (X)Emacs.
- A Windows (XP/2k) command prompt with Gary Bishop's support extensions. Gary's extensions are discussed in Sec. 2.3.
- A Windows (XP/2k) CygWin shell. Although some users have reported problems; it is not clear whether there is an issue for everyone or only under specific configurations. If you have full color support under cygwin, please post to the IPython mailing list so this issue can be resolved for all users.

These have shown problems:

- Windows command prompt in WinXP/2k logged into a Linux machine via telnet or ssh.
- Windows native command prompt in WinXP/2k, without Gary Bishop's extensions. Once Gary's readline library is installed, the normal WinXP/2k command prompt works perfectly.

Currently the following color schemes are available:

- `NoColor`: uses no color escapes at all (all escapes are empty `` `` strings). This 'scheme' is thus fully safe to use in any terminal.
- `Linux`: works well in Linux console type environments: dark background with light fonts. It uses bright colors for information, so it is difficult to read if you have a light colored background.
- `LightBG`: the basic colors are similar to those in the `Linux` scheme but darker. It is easy to read in terminals with light backgrounds.

IPython uses colors for two main groups of things: prompts and tracebacks which are directly printed to the terminal, and the object introspection system which passes large sets of data through a pager.

### Input/Output prompts and exception tracebacks

You can test whether the colored prompts and tracebacks work on your system interactively by typing `'%colors Linux'` at the prompt (use '`%colors LightBG'` if your terminal has a light background). If the input prompt shows garbage like:
`[0;32mIn [[1;32m1[0;32m]: [0;00m`
instead of (in color) something like:
`In [1]:`
this means that your terminal doesn't properly handle color escape sequences. You can go to a 'no color' mode by typing '`%colors NoColor`'.

You can try using a different terminal emulator program (Emacs users, see below). To permanently set your color preferences, edit the file `$HOME/.ipython/ipythonrc` and set the `colors` option to the desired value.

### Object details (types, docstrings, source code, etc.)

IPython has a set of special functions for studying the objects you are working with, discussed in detail in Sec. 6.4. But this system relies on passing information which is longer than your screen through a data pager, such as the common Unix `less` and `more` programs. In order to be able to see this information in color, your pager needs to be properly configured. I strongly recommend using `less` instead of `more`, as it seems that `more` simply can not understand colored text correctly.

In order to configure `less` as your default pager, do the following:

1. Set the environment `PAGER` variable to `less`.
2. Set the environment `LESS` variable to `-r` (plus any other options you always want to pass to `less` by default). This tells `less` to properly interpret control sequences, which is how color information is given to your terminal.

For the `csh` or `tcsh` shells, add to your `~/.cshrc` file the lines:

`setenv PAGER less`
`setenv LESS -r`

There is similar syntax for other Unix shells, look at your system documentation for details.

If you are on a system which lacks proper data pagers (such as Windows), IPython will use a very limited builtin pager.

##
(X)Emacs configuration

Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, currently (X)Emacs and IPython get along very well.

Important note: You will need to use a recent enough version of `python-mode.el`, along with the file `ipython.el`. You can check that the version you have of `python-mode.el` is new enough by either looking at the revision number in the file itself, or asking for it in (X)Emacs via `M-x py-version`. Versions 4.68 and newer contain the necessary fixes for proper IPython support.

The file `ipython.el` is included with the IPython distribution, in the documentation directory (where this manual resides in PDF and HTML formats).

Once you put these files in your Emacs path, all you need in your `.emacs` file is:

  (require 'ipython)

This should give you full support for executing code snippets via IPython, opening IPython as your Python shell via `C-c !`, etc.

If you happen to get garbage instead of colored prompts as described in the previous section, you may need to set also in your `.emacs` file:

  (setq ansi-color-for-comint-mode t)

### Notes

- There is one caveat you should be aware of: you must start the IPython shell before attempting to execute any code regions via `C-c |`. Simply type `C-c !` to start IPython before passing any code regions to the interpreter, and you shouldn't experience any problems.
  This is due to a bug in Python itself, which has been fixed for Python 2.3, but exists as of Python 2.2.2 (reported as SF bug [ 737947 ]).
- The (X)Emacs support is maintained by Alexander Schmolck, so all comments/requests should be directed to him through the IPython mailing lists.
- This code is still somewhat experimental so it's a bit rough around the edges (although in practice, it works quite well).
- Be aware that if you customize `py-python-command` previously, this value will override what `ipython.el` does (because loading the customization variables comes later).