Next: Interactive use
Up: IPython An enhanced Interactive
Previous: Upgrading from a previous
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.
Options
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 'no' form
(-nooption instead of -option) to turn the feature off.
- [-help:]print a help message and exit.
- [-no|automagic:]make magic commands automatic
(without needing their first character to be @). Type @magic
at the IPython prompt for more information.
- [-no|banner:]Print the initial information banner
(default on).
- [-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|c <scheme>:]Color scheme for prompts and exception
reporting. Currently implemented: NoColor, Linux and LightBG.
- [-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()].
- [-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. Defaults to
$IPYTHONDIR/log. 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 '%n' in the string. Don't forget to quote
strings with spaces embedded in them. Default: 'In [%n]:'
- [-prompt_in2|pi2 <string>:]Similar to the previous
option, but used for the continuation prompts. In this case, the number
(%n) is replaced by as many dots as there are digits in the number
(so you can have your continuation prompt aligned with your input prompt).
Default: ' .%n.:' (note three spaces at the start for alignment
with 'In [%n]')
- [-prompt_out|po <string>:]String used for output prompts,
also uses numbers like prompt_in1. Default: 'Out[%n]:'
- [-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.
- [-xmode]<modename>: Mode for
exception reporting. Valid modes: Plain and Verbose. See the sample ipythonrc
file for details on this option.
Next: Interactive use
Up: IPython An enhanced Interactive
Previous: Upgrading from a previous
Fernando Perez
2002-04-29