1
.\" Hey, EMACS: -*- nroff -*-
2
.\" First parameter, NAME, should be all caps
3
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
4
.\" other parameters are allowed: see man(7), man(1)
5
.TH IPYTHON 1 "November 30, 2004"
6
.\" Please adjust this date whenever revising the manpage.
8
.\" Some roff macros, for reference:
9
.\" .nh disable hyphenation
10
.\" .hy enable hyphenation
11
.\" .ad l left justify
12
.\" .ad b justify to both left and right margins
13
.\" .nf disable filling
14
.\" .fi enable filling
15
.\" .br insert line break
16
.\" .sp <n> insert n+1 empty lines
17
.\" for manpage-specific macros, see man(7) and groff_man(7)
18
.\" .SH section heading
19
.\" .SS secondary section heading
22
.\" To preview this page as plain text: nroff -man ipython.1
25
ipython \- An Enhanced Interactive Python
28
.RI [ options ] " files" ...
30
An interactive Python shell with automatic history (input and output),
31
dynamic object introspection, easier configuration, command
32
completion, access to the system shell, integration with numerical and
33
scientific computing tools, and more.
34
.SH SPECIAL THREADING OPTIONS
35
The following special options are ONLY valid at the beginning of the command
36
line, and not later. This is because they control the initialization of
37
ipython itself, before the normal option-handling mechanism is active.
39
.B \-gthread, \-qthread, \-q4thread, \-wthread, \-pylab
40
Only ONE of these can be given, and it can only be given as the first option
41
passed to IPython (it will have no effect in any other position). They provide
42
threading support for the GTK, QT3, QT4 and WXWidgets toolkits, and for the
46
With any of the first four options, IPython starts running a separate thread
47
for the graphical toolkit's operation, so that you can open and control
48
graphical elements from within an IPython command line, without blocking. All
49
four provide essentially the same functionality, respectively for GTK, QT3, QT4
50
and WXWidgets (via their Python interfaces).
53
Note that with \-wthread, you can additionally use the \-wxversion option to
54
request a specific version of wx to be used. This requires that you have the
55
'wxversion' Python module installed, which is part of recent wxPython
59
If \-pylab is given, IPython loads special support for the matplotlib library
60
(http://matplotlib.sourceforge.net), allowing interactive usage of any of its
61
backends as defined in the user's .matplotlibrc file. It automatically
62
activates GTK, QT or WX threading for IPyhton if the choice of matplotlib
63
backend requires it. It also modifies the %run command to correctly execute
64
(without blocking) any matplotlib-based script which calls show() at the end.
67
The \-g/q/q4/wthread options, and \-pylab (if matplotlib is configured to use
68
GTK, QT or WX), will normally block Tk graphical interfaces. This means that
69
when GTK, QT or WX threading is active, any attempt to open a Tk GUI will
70
result in a dead window, and possibly cause the Python interpreter to crash.
71
An extra option, \-tk, is available to address this issue. It can ONLY be
72
given as a SECOND option after any of the above (\-gthread, \-qthread,
73
\-wthread or \-pylab).
76
If \-tk is given, IPython will try to coordinate Tk threading with GTK, QT or
77
WX. This is however potentially unreliable, and you will have to test on your
78
platform and Python configuration to determine whether it works for you.
79
Debian users have reported success, apparently due to the fact that Debian
80
builds all of Tcl, Tk, Tkinter and Python with pthreads support. Under other
81
Linux environments (such as Fedora Core 2), this option has caused random
82
crashes and lockups of the Python interpreter. Under other operating systems
83
(Mac OSX and Windows), you'll need to try it to find out, since currently no
84
user reports are available.
87
There is unfortunately no way for IPython to determine at runtime whether \-tk
88
will work reliably or not, so you will need to do some experiments before
89
relying on it for regular work.
92
After the above threading options have been given, regular options can follow
93
in any order. All options can be abbreviated to their shortest non-ambiguous
94
form and are case-sensitive. One or two dashes can be used. Some options
95
have an alternate short form, indicated after a |.
98
Most options can also be set from your ipythonrc configuration file.
99
See the provided examples for assistance. Options given on the
100
commandline override the values set in the ipythonrc file.
103
All options with a [no] prepended can be specified in negated form
104
(\-nooption instead of \-option) to turn the feature off.
107
Show summary of options.
110
Make IPython automatically call any callable object even if you didn't type
111
explicit parentheses. For example, 'str 43' becomes
112
'str(43)' automatically. The value can be '0' to disable the
113
feature, '1' for 'smart' autocall, where it is not applied if
114
there are no more arguments on the line, and '2' for 'full'
115
autocall, where all callable objects are automatically called
116
(even if no arguments are present). The default is '1'.
119
Turn automatic indentation on/off.
122
Make magic commands automatic (without needing their first character
123
to be %). Type %magic at the IPython prompt for more information.
125
.B \-[no]autoedit_syntax
126
When a syntax error occurs after editing a file, automatically open the file
127
to the trouble causing line for convenient fixing.
130
Print the intial information banner (default on).
133
Execute the given command string, and set sys.argv to ['c']. This is similar
134
to the \-c option in the normal Python interpreter.
136
.B \-cache_size|cs <n>
137
Size of the output cache (maximum number of entries to hold in
138
memory). The default is 1000, you can change it permanently in your
139
config file. Setting it to 0 completely disables the caching system,
140
and the minimum value accepted is 20 (if you provide a value less than
141
20, it is reset to 0 and a warning is issued). This limit is defined
142
because otherwise you'll spend more time re-flushing a too small cache
146
Gives IPython a similar feel to the classic Python prompt.
149
Color scheme for prompts and exception reporting. Currently
150
implemented: NoColor, Linux, and LightBG.
153
IPython can display information about objects via a set of functions,
154
and optionally can use colors for this, syntax highlighting source
155
code and various other elements. However, because this information is
156
passed through a pager (like 'less') and many pagers get confused with
157
color codes, this option is off by default. You can test it and turn
158
it on permanently in your ipythonrc file if it works for you. As a
159
reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
160
that in RedHat 7.2 doesn't.
163
Test it and turn it on permanently if it works with your system. The
164
magic function @color_info allows you to toggle this interactively for
167
.B \-[no]confirm_exit
168
Set to confirm when you try to exit IPython with an EOF (Control-D in
169
Unix, Control-Z/Enter in Windows). Note that using the magic functions
170
@Exit or @Quit you can force a direct exit, bypassing any
174
Show information about the loading process. Very useful to pin down
175
problems with your configuration files or to get details about session
179
IPython can use the deep_reload module which reloads changes in
180
modules recursively (it replaces the reload() function, so you don't
181
need to change anything to use it). deep_reload() forces a full reload
182
of modules whose code may have changed, which the default reload()
186
When deep_reload is off, IPython will use the normal reload(), but
187
deep_reload will still be available as dreload(). This feature is off
188
by default [which means that you have both normal reload() and
192
Which editor to use with the @edit command. By default, IPython will
193
honor your EDITOR environment variable (if not set, vi is the Unix
194
default and notepad the Windows one). Since this editor is invoked on
195
the fly by IPython and is meant for editing small code snippets, you
196
may want to use a small, lightweight editor here (in case your default
197
EDITOR is something like Emacs).
199
.B \-ipythondir <name>
200
The name of your IPython configuration directory IPYTHONDIR. This can
201
also be specified through the environment variable IPYTHONDIR.
204
Generate a log file of all input. The file is named ipython_log.py in your
205
current directory (which prevents logs from multiple IPython sessions from
206
trampling each other). You can use this to later restore a session by loading
207
your logfile as a file to be executed with option -logplay (see below).
210
Specify the name of your logfile.
213
Replay a previous log. For restoring a session as close as possible to
214
the state you left it in, use this option (don't just run the
215
logfile). With \-logplay, IPython will try to reconstruct the previous
216
working environment in full, not just execute the commands in the
220
When a session is restored, logging is automatically turned on again
221
with the name of the logfile it was invoked with (it is read from the
222
log header). So once you've turned logging on for a session, you can
223
quit IPython and reload it as many times as you want and it will
224
continue to log its history and restore from the beginning every time.
227
Caveats: there are limitations in this option. The history variables
228
_i*,_* and _dh don't get restored properly. In the future we will try
229
to implement full session saving by writing and retrieving a
230
'snapshot' of the memory state of IPython. But our first attempts
231
failed because of inherent limitations of Python's Pickle module, so
232
this may have to wait.
235
Print messages which IPython collects about its startup process
239
Automatically call the pdb debugger after every uncaught exception. If
240
you are used to debugging using pdb, this puts you automatically
241
inside of it after any call (either in IPython or in code called by
242
it) which triggers an exception which goes uncaught.
245
IPython can optionally use the pprint (pretty printer) module for
246
displaying results. pprint tends to give a nicer display of nested
247
data structures. If you like it, you can turn it on permanently in
248
your config file (default off).
250
.B \-profile|p <name>
251
Assume that your config file is ipythonrc-<name> (looks in current dir
252
first, then in IPYTHONDIR). This is a quick way to keep and load
253
multiple config files for different tasks, especially if you use the
254
include option of config files. You can keep a basic
255
IPYTHONDIR/ipythonrc file and then have other 'profiles' which include
256
this one and load extra things for particular tasks. For example:
259
1) $HOME/.ipython/ipythonrc : load basic things you always want.
261
2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-related
264
3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
268
Since it is possible to create an endless loop by having circular file
269
inclusions, IPython will stop if it reaches 15 recursive inclusions.
271
.B \-prompt_in1|pi1 <string>
272
Specify the string used for input prompts. Note that if you are using
273
numbered prompts, the number is represented with a '\\#' in the
274
string. Don't forget to quote strings with spaces embedded in
275
them. Default: 'In [\\#]: '.
278
Most bash-like escapes can be used to customize IPython's prompts, as well as
279
a few additional ones which are IPython-specific. All valid prompt escapes
280
are described in detail in the Customization section of the IPython HTML/PDF
283
.B \-prompt_in2|pi2 <string>
284
Similar to the previous option, but used for the continuation prompts. The
285
special sequence '\\D' is similar to '\\#', but with all digits replaced dots
286
(so you can have your continuation prompt aligned with your input
287
prompt). Default: ' .\\D.: ' (note three spaces at the start for alignment
290
.B \-prompt_out|po <string>
291
String used for output prompts, also uses numbers like prompt_in1.
292
Default: 'Out[\\#]:'.
295
Start in bare bones mode (no config file loaded).
298
Name of your IPython resource configuration file. normally IPython
299
loads ipythonrc (from current directory) or IPYTHONDIR/ipythonrc. If
300
the loading of your config file fails, IPython starts with a bare
301
bones configuration (no modules loaded at all).
304
Use the readline library, which is needed to support name completion
305
and command history, among other things. It is enabled by default, but
306
may cause problems for users of X/Emacs in Python comint or shell
310
Note that emacs 'eterm' buffers (opened with M-x term) support
311
IPython's readline and syntax coloring fine, only 'emacs' (M-x shell
312
and C-c !) buffers do not.
314
.B \-screen_length|sl <n>
315
Number of lines of your screen. This is used to control printing of
316
very long strings. Strings longer than this number of lines will be
317
sent through a pager instead of directly printed.
320
The default value for this is 0, which means IPython will auto-detect
321
your screen size every time it needs to print certain potentially long
322
strings (this doesn't change the behavior of the 'print' keyword, it's
323
only triggered internally). If for some reason this isn't working well
324
(it needs curses support), specify it yourself. Otherwise don't change
327
.B \-separate_in|si <string>
328
Separator before input prompts. Default '\n'.
330
.B \-separate_out|so <string>
331
Separator before output prompts. Default: 0 (nothing).
333
.B \-separate_out2|so2 <string>
334
Separator after output prompts. Default: 0 (nothing).
337
Shorthand for '\-separate_in 0 \-separate_out 0 \-separate_out2 0'.
338
Simply removes all input/output separators.
341
Allows you to upgrade your IPYTHONDIR configuration when you install a
342
new version of IPython. Since new versions may include new command
343
lines options or example files, this copies updated ipythonrc-type
344
files. However, it backs up (with a .old extension) all files which
345
it overwrites so that you can merge back any custimizations you might
346
have in your personal files.
349
Print version information and exit.
351
.B -wxversion <string>
352
Select a specific version of wxPython (used in conjunction with
353
\-wthread). Requires the wxversion module, part of recent wxPython
356
.B \-xmode <modename>
357
Mode for exception reporting. The valid modes are Plain, Context, and
361
\- Plain: similar to python's normal traceback printing.
364
\- Context: prints 5 lines of context source code around each line in the
368
\- Verbose: similar to Context, but additionally prints the variables
369
currently visible where the exception happened (shortening their strings if
370
too long). This can potentially be very slow, if you happen to have a huge
371
data structure whose string representation is complex to compute. Your
372
computer may appear to freeze for a while with cpu usage at 100%. If this
373
occurs, you can cancel the traceback with Ctrl-C (maybe hitting it more than
377
It is possible to start an IPython instance inside your own Python
378
programs. In the documentation example files there are some
379
illustrations on how to do this.
382
This feature allows you to evalutate dynamically the state of your
383
code, operate with your variables, analyze them, etc. Note however
384
that any changes you make to values while in the shell do NOT
385
propagate back to the running code, so it is safe to modify your
386
values because you won't break your code in bizarre ways by doing so.
388
IPython was written by Fernando Perez <fperez@colorado.edu>, based on earlier
389
code by Janko Hauser <jh@comunit.de> and Nathaniel Gray
390
<n8gray@caltech.edu>. This manual page was written by Jack Moffitt
391
<jack@xiph.org>, for the Debian project (but may be used by others).
added
removed
doc/ipython.1
