Subsections
You start IPython with the command:
$ ipython [options] files
If invoked with no options, it executes all the files listed in sequence and drops
you into the interpreter while still acknowledging any options you may have set
in your ipythonrc file. This behavior is different from standard Python, which
when called as python -i will only execute one file and ignore your configuration
setup.
Please note that some of the configuration options are not available at the command
line, simply because they are not practical here. Look into your ipythonrc configuration
file for details on those. This file typically installed in the $HOME/.ipython
directory. For Windows users, $HOME resolves to C:\\Documents
and Settings\\YourUserName in most instances. In
the rest of this text, we will refer to this directory as IPYTHONDIR.
Special Threading Options
The following special options are ONLY valid at the beginning of the command line,
and not later. This is because they control the initial- ization of ipython itself,
before the normal option-handling mechanism is active.
- [-gthread, -qthread, -wthread, -pylab:]Only one of
these can be given, and it can only be given as the first option passed to IPython
(it will have no effect in any other position). They provide threading support
for the GTK Qt and WXPython toolkits, and for the matplotlib library.
- [ ]With any of the first three options, IPython starts running a separate thread
for the graphical toolkit's operation, so that you can open and control graphical
elements from within an IPython command line, without blocking. All three provide
essentially the same functionality, respectively for GTK, QT and WXWidgets (via
their Python interfaces).
- [ ]Note that with -wthread, you can additionally use the -wxversion
option to request a specific version of wx to be used. This requires that you have
the wxversion Python module installed, which is part of recent wxPython
distributions.
- [ ]If -pylab is given, IPython loads special support for the mat plotlib
library (http://matplotlib.sourceforge.net), allowing interactive usage
of any of its backends as defined in the user's ~/.matplotlib/matplotlibrc
file. It automatically activates GTK, Qt or WX threading for IPyhton if the choice
of matplotlib backend requires it. It also modifies the %run command
to correctly execute (without blocking) any matplotlib-based script which calls
show() at the end.
- [-tk]The -g/q/wthread options, and -pylab
(if matplotlib is configured to use GTK, Qt or WX), will normally block Tk graphical
interfaces. This means that when either GTK, Qt or WX threading is active, any
attempt to open a Tk GUI will result in a dead window, and possibly cause the Python
interpreter to crash. An extra option, -tk, is available to address this
issue. It can only be given as a second option after any of the above
(-gthread, -wthread or -pylab).
- [ ]If -tk is given, IPython will try to coordinate Tk threading with
GTK, Qt or WX. This is however potentially unreliable, and you will have to test
on your platform and Python configuration to determine whether it works for you.
Debian users have reported success, apparently due to the fact that Debian builds
all of Tcl, Tk, Tkinter and Python with pthreads support. Under other Linux environments
(such as Fedora Core 2/3), this option has caused random crashes and lockups of
the Python interpreter. Under other operating systems (Mac OSX and Windows), you'll
need to try it to find out, since currently no user reports are available.
- [ ]There is unfortunately no way for IPython to determine at run time whether
-tk will work reliably or not, so you will need to do some experiments
before relying on it for regular work.
Regular Options
After the above threading options have been given, regular options can follow in
any order. All options can be abbreviated to their shortest non-ambiguous form
and are case-sensitive. One or two dashes can be used. Some options have an alternate
short form, indicated after a |.
Most options can also be set from your ipythonrc configuration file. See the provided
example for more details on what the options do. Options given at the command line
override the values set in the ipythonrc file.
All options with a [no] prepended can be specified in negated form
(-nooption instead of -option) to turn the feature off.
- [-help:]print a help message and exit.
- [-pylab:]this can only be given as the first option
passed to IPython (it will have no effect in any other position). It adds special
support for the matplotlib library (http://matplotlib.sourceforge.net http://matplotlib.sourceforge.net),
allowing interactive usage of any of its backends as defined in the user's .matplotlibrc
file. It automatically activates GTK or WX threading for IPyhton if the choice
of matplotlib backend requires it. It also modifies the %run command
to correctly execute (without blocking) any matplotlib-based script which calls
show() at the end. See Sec. 15 for more details.
- [-autocall]<val>: Make IPython automatically
call any callable object even if you didn't type explicit parentheses. For example,
`str 43' becomes `str(43)' automatically. The value can be `0' to disable the feature,
`1' for smart autocall, where it is not applied if there are no more arguments
on the line, and `2' for full autocall, where all callable objects are automatically
called (even if no arguments are present). The default is `1'.
- [-[no]autoindent:]Turn automatic indentation on/off.
- [-[no]automagic:]make magic commands automatic
(without needing their first character to be %). Type %magic
at the IPython prompt for more information.
- [-[no]autoedit_syntax:]When a syntax error occurs after
editing a file, automatically open the file to the trouble causing line for convenient
fixing.
- [-[no]banner:]Print the initial information banner
(default on).
- [-c <command>:]execute the given command string, and set sys.argv
to ['c']. This is similar to the -c option in the normal
Python interpreter.
- [-cache_size|cs <n>:]size of the output cache (maximum
number of entries to hold in memory). The default is 1000, you can change it permanently
in your config file. Setting it to 0 completely disables the caching system, and
the minimum value accepted is 20 (if you provide a value less than 20, it is reset
to 0 and a warning is issued) This limit is defined because otherwise you'll spend
more time re-flushing a too small cache than working.
- [-classic|cl:]Gives IPython a similar feel to the classic
Python prompt.
- [-colors <scheme>:]Color scheme for prompts and exception reporting.
Currently implemented: NoColor, Linux and LightBG.
- [-[no]color_info:]IPython can display information about
objects via a set of functions, and optionally can use colors for this, syntax
highlighting source code and various other elements. However, because this information
is passed through a pager (like 'less') and many pagers get confused with color
codes, this option is off by default. You can test it and turn it on permanently
in your ipythonrc file if it works for you. As a reference, the 'less' pager supplied
with Mandrake 8.2 works ok, but that in RedHat 7.2 doesn't.
- [ ]Test it and turn it on permanently if it works with your system. The magic
function %color_info allows you to toggle this interactively for testing.
- [-[no]debug:]Show information about the loading process.
Very useful to pin down problems with your configuration files or to get details
about session restores.
- [-[no]deep_reload:]IPython can use the deep_reload
module which reloads changes in modules recursively (it replaces the reload()
function, so you don't need to change anything to use it). deep_reload()
forces a full reload of modules whose code may have changed, which the default
reload() function does not.
- [ ]When deep_reload is off, IPython will use the normal reload(), but
deep_reload will still be available as dreload(). This feature is off
by default [which means that you have both normal reload() and dreload()].
- [-editor <name>:]Which editor to use with the %edit
command. By default, IPython will honor your EDITOR environment variable
(if not set, vi is the Unix default and notepad the Windows one). Since this editor
is invoked on the fly by IPython and is meant for editing small code snippets,
you may want to use a small, lightweight editor here (in case your default EDITOR
is something like Emacs).
- [-ipythondir <name>:]name of your IPython configuration
directory IPYTHONDIR. This can also be specified through the environment
variable IPYTHONDIR.
- [-log|l:]generate a log file of all input. The file is named
ipython_log.py in your current directory (which prevents logs from multiple
IPython sessions from trampling each other). You can use this to later restore
a session by loading your logfile as a file to be executed with option -logplay
(see below).
- [-logfile|lf <name>:]specify the name of your logfile.
- [-logplay|lp <name>:]you can replay a previous log.
For restoring a session as close as possible to the state you left it in, use this
option (don't just run the logfile). With -logplay, IPython will try to
reconstruct the previous working environment in full, not just execute the commands
in the logfile.
- [ ]When a session is restored, logging is automatically turned on again with
the name of the logfile it was invoked with (it is read from the log header). So
once you've turned logging on for a session, you can quit IPython and reload it
as many times as you want and it will continue to log its history and restore from
the beginning every time.
- [ ]Caveats: there are limitations in this option. The history variables _i*,_*
and _dh don't get restored properly. In the future we will try to implement
full session saving by writing and retrieving a 'snapshot' of the memory state
of IPython. But our first attempts failed because of inherent limitations of Python's
Pickle module, so this may have to wait.
- [-[no]messages:]Print messages which IPython collects
about its startup process (default on).
- [-[no]pdb:]Automatically call the pdb debugger after every
uncaught exception. If you are used to debugging using pdb, this puts you automatically
inside of it after any call (either in IPython or in code called by it) which triggers
an exception which goes uncaught.
- [-[no]pprint:]ipython can optionally use the pprint
(pretty printer) module for displaying results. pprint tends to give a nicer display
of nested data structures. If you like it, you can turn it on permanently in your
config file (default off).
- [-profile|p]<name>: assume that your
config file is ipythonrc-<name> (looks in current dir first, then in IPYTHONDIR).
This is a quick way to keep and load multiple config files for different tasks,
especially if you use the include option of config files. You can keep a basic
IPYTHONDIR/ipythonrc file and then have other 'profiles' which include
this one and load extra things for particular tasks. For example:
- [ ]1. $HOME/.ipython/ipythonrc : load basic things you always
want.
- [ ]2. $HOME/.ipython/ipythonrc-math : load (1) and basic math-related
modules.
- [ ]3. $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric
and plotting modules.
- [ ]Since it is possible to create an endless loop by having circular file inclusions,
IPython will stop if it reaches 15 recursive inclusions.
- [-prompt_in1|pi1 <string>:]Specify the string used for input
prompts. Note that if you are using numbered prompts, the number is represented
with a '\#' in the string. Don't forget to quote strings with spaces
embedded in them. Default: 'In [\#]:'. Sec. 7.2
discusses in detail all the available escapes to customize your prompts.
- [-prompt_in2|pi2 <string>:]Similar to the previous option,
but used for the continuation prompts. The special sequence '\D'
is similar to '\#', but with all digits replaced dots
(so you can have your continuation prompt aligned with your input prompt). Default:
' .\D.:' (note three spaces at the start for alignment
with 'In [\#]').
- [-prompt_out|po <string>:]String used for output prompts,
also uses numbers like prompt_in1. Default: 'Out[\#]:'
- [-quick:]start in bare bones mode (no config file loaded).
- [-rcfile <name>:]name of your IPython resource configuration
file. Normally IPython loads ipythonrc (from current directory) or IPYTHONDIR/ipythonrc.
- [ ]If the loading of your config file fails, IPython starts with a bare bones
configuration (no modules loaded at all).
- [-[no]readline:]use the readline library, which is needed
to support name completion and command history, among other things. It is enabled
by default, but may cause problems for users of X/Emacs in Python comint or shell
buffers.
- [ ]Note that X/Emacs 'eterm' buffers (opened with M-x term) support
IPython's readline and syntax coloring fine, only 'emacs' (M-x shell
and C-c !) buffers do not.
- [-screen_length|sl <n>:]number of lines of your screen.
This is used to control printing of very long strings. Strings longer than this
number of lines will be sent through a pager instead of directly printed.
- [ ]The default value for this is 0, which means IPython will auto-detect your
screen size every time it needs to print certain potentially long strings (this
doesn't change the behavior of the 'print' keyword, it's only triggered internally).
If for some reason this isn't working well (it needs curses support), specify it
yourself. Otherwise don't change the default.
- [-separate_in|si <string>:]separator before input
prompts. Default: '\n'
- [-separate_out|so <string>:]separator before output prompts.
Default: nothing.
- [-separate_out2|so2 <string>:]separator after output
prompts. Default: nothing.
- [ ]For these three options, use the value 0 to specify no separator.
- [-nosep:]shorthand for '-SeparateIn 0 -SeparateOut
0 -SeparateOut2 0'. Simply removes all input/output separators.
- [-upgrade:]allows you to upgrade your IPYTHONDIR configuration
when you install a new version of IPython. Since new versions may include new command
line options or example files, this copies updated ipythonrc-type files. However,
it backs up (with a .old extension) all files which it overwrites so that
you can merge back any customizations you might have in your personal files.
- [-Version:]print version information and exit.
- [-wxversion <string>:]Select a specific version of wxPython
(used in conjunction with -wthread). Requires the wxversion module, part
of recent wxPython distributions
- [-xmode <modename>:]Mode for exception reporting.
- [ ]Valid modes: Plain, Context and Verbose.
- [ ]Plain: similar to python's normal traceback printing.
- [ ]Context: prints 5 lines of context source code around each line in the traceback.
- [ ]Verbose: similar to Context, but additionally prints the variables currently
visible where the exception happened (shortening their strings if too long). This
can potentially be very slow, if you happen to have a huge data structure whose
string representation is complex to compute. Your computer may appear to freeze
for a while with cpu usage at 100%. If this occurs, you can cancel the traceback
with Ctrl-C (maybe hitting it more than once).
Fernando Perez
2006-06-06