1IPYTHON(1) General Commands Manual IPYTHON(1)
2
6 ipython - An Enhanced Interactive Python
7
9 ipython [options] files...
10
12 An interactive Python shell with automatic history (input and output),
13 dynamic object introspection, easier configuration, command completion,
14 access to the system shell, integration with numerical and scientific
15 computing tools, and more.
16
18 The following special options are ONLY valid at the beginning of the
19 command line, and not later. This is because they control the initial‐
20 ization of ipython itself, before the normal option-handling mechanism
21 is active.
22 -gthread, -qthread, -q4thread, -wthread, -pylab
24 Only ONE of these can be given, and it can only be given as the
25 first option passed to IPython (it will have no effect in any
26 other position). They provide threading support for the GTK,
27 QT3, QT4 and WXWidgets toolkits, for the matplotlib library and
28 Twisted reactor.
29 With any of the first four options, IPython starts running a
31 separate thread for the graphical toolkit's operation, so that
32 you can open and control graphical elements from within an
33 IPython command line, without blocking. All four provide essen‐
34 tially the same functionality, respectively for GTK, QT3, QT4
35 and WXWidgets (via their Python interfaces).
36 Note that with -wthread, you can additionally use the -wxversion
38 option to request a specific version of wx to be used. This
39 requires that you have the wxversion Python module installed,
40 which is part of recent wxPython distributions.
41 If -pylab is given, IPython loads special support for the mat‐
43 plotlib library (http://matplotlib.sourceforge.net), allowing
44 interactive usage of any of its backends as defined in the
45 user's .matplotlibrc file. It automatically activates GTK, QT
46 or WX threading for IPyhton if the choice of matplotlib backend
47 requires it. It also modifies the %run command to correctly
48 execute (without blocking) any matplotlib-based script which
49 calls show() at the end.
50 -tk The -g/q/q4/wthread options, and -pylab (if matplotlib is con‐
52 figured to use GTK, QT or WX), will normally block Tk graphical
53 interfaces. This means that when GTK, QT or WX threading is
54 active, any attempt to open a Tk GUI will result in a dead win‐
55 dow, and possibly cause the Python interpreter to crash. An
56 extra option, -tk, is available to address this issue. It can
57 ONLY be given as a SECOND option after any of the above (-gth‐
58 read, -qthread, -wthread or -pylab).
59 If -tk is given, IPython will try to coordinate Tk threading
61 with GTK, QT or WX. This is however potentially unreliable, and
62 you will have to test on your platform and Python configuration
63 to determine whether it works for you. Debian users have
64 reported success, apparently due to the fact that Debian builds
65 all of Tcl, Tk, Tkinter and Python with pthreads support. Under
66 other Linux environments (such as Fedora Core 2), this option
67 has caused random crashes and lockups of the Python interpreter.
68 Under other operating systems (Mac OSX and Windows), you'll need
69 to try it to find out, since currently no user reports are
70 available.
71 There is unfortunately no way for IPython to determine at run‐
73 time whether -tk will work reliably or not, so you will need to
74 do some experiments before relying on it for regular work.
75
77 After the above threading options have been given, regular options can
78 follow in any order. All options can be abbreviated to their shortest
79 non-ambiguous form and are case-sensitive. One or two dashes can be
80 used. Some options have an alternate short form, indicated after a |.
81 Most options can also be set from your ipythonrc configuration file.
83 See the provided examples for assistance. Options given on the comman‐
84 dline override the values set in the ipythonrc file.
85 All options with a [no] prepended can be specified in negated form
87 (-nooption instead of -option) to turn the feature off.
88 -h, --help
90 Show summary of options.
91 -autocall <val>
93 Make IPython automatically call any callable object even if you
94 didn't type explicit parentheses. For example, 'str 43' becomes
95 str(43) automatically. The value can be '0' to disable the fea‐
96 ture, '1' for 'smart' autocall, where it is not applied if there
97 are no more arguments on the line, and '2' for 'full' autocall,
98 where all callable objects are automatically called (even if no
99 arguments are present). The default is '1'.
100 -[no]autoindent
102 Turn automatic indentation on/off.
103 -[no]automagic
105 Make magic commands automatic (without needing their first char‐
106 acter to be %). Type %magic at the IPython prompt for more
107 information.
108 -[no]autoedit_syntax
110 When a syntax error occurs after editing a file, automatically
111 open the file to the trouble causing line for convenient fixing.
112 -[no]banner
114 Print the intial information banner (default on).
115 -c <command>
117 Execute the given command string, and set sys.argv to ['c'].
118 This is similar to the -c option in the normal Python inter‐
119 preter.
120 -cache_size|cs <n>
122 Size of the output cache (maximum number of entries to hold in
123 memory). The default is 1000, you can change it permanently in
124 your config file. Setting it to 0 completely disables the
125 caching system, and the minimum value accepted is 20 (if you
126 provide a value less than 20, it is reset to 0 and a warning is
127 issued). This limit is defined because otherwise you'll spend
128 more time re-flushing a too small cache than working.
129 -classic|cl
131 Gives IPython a similar feel to the classic Python prompt.
132 -colors <scheme>
134 Color scheme for prompts and exception reporting. Currently
135 implemented: NoColor, Linux, and LightBG.
136 -[no]color_info
138 IPython can display information about objects via a set of func‐
139 tions, and optionally can use colors for this, syntax highlight‐
140 ing source code and various other elements. However, because
141 this information is passed through a pager (like 'less') and
142 many pagers get confused with color codes, this option is off by
143 default. You can test it and turn it on permanently in your
144 ipythonrc file if it works for you. As a reference, the 'less'
145 pager supplied with Mandrake 8.2 works ok, but that in RedHat
146 7.2 doesn't.
147 Test it and turn it on permanently if it works with your system.
149 The magic function @color_info allows you to toggle this inter‐
150 actively for testing.
151 -[no]confirm_exit
153 Set to confirm when you try to exit IPython with an EOF (Con‐
154 trol-D in Unix, Control-Z/Enter in Windows). Note that using the
155 magic functions @Exit or @Quit you can force a direct exit,
156 bypassing any confirmation.
157 -[no]debug
159 Show information about the loading process. Very useful to pin
160 down problems with your configuration files or to get details
161 about session restores.
162 -[no]deep_reload
164 IPython can use the deep_reload module which reloads changes in
165 modules recursively (it replaces the reload() function, so you
166 don't need to change anything to use it). deep_reload() forces a
167 full reload of modules whose code may have changed, which the
168 default reload() function does not.
169 When deep_reload is off, IPython will use the normal reload(),
171 but deep_reload will still be available as dreload(). This fea‐
172 ture is off by default [which means that you have both normal
173 reload() and dreload()].
174 -editor <name>
176 Which editor to use with the @edit command. By default, IPython
177 will honor your EDITOR environment variable (if not set, vi is
178 the Unix default and notepad the Windows one). Since this editor
179 is invoked on the fly by IPython and is meant for editing small
180 code snippets, you may want to use a small, lightweight editor
181 here (in case your default EDITOR is something like Emacs).
182 -ipythondir <name>
184 The name of your IPython configuration directory IPYTHONDIR.
185 This can also be specified through the environment variable
186 IPYTHONDIR.
187 -log|l Generate a log file of all input. The file is named
189 ipython_log.py in your current directory (which prevents logs
190 from multiple IPython sessions from trampling each other). You
191 can use this to later restore a session by loading your logfile
192 as a file to be executed with option -logplay (see below).
193 -logfile|lf
195 Specify the name of your logfile.
196 -logplay|lp
198 Replay a previous log. For restoring a session as close as pos‐
199 sible to the state you left it in, use this option (don't just
200 run the logfile). With -logplay, IPython will try to reconstruct
201 the previous working environment in full, not just execute the
202 commands in the logfile.
203 When a session is restored, logging is automatically turned on
205 again with the name of the logfile it was invoked with (it is
206 read from the log header). So once you've turned logging on for
207 a session, you can quit IPython and reload it as many times as
208 you want and it will continue to log its history and restore
209 from the beginning every time.
210 Caveats: there are limitations in this option. The history vari‐
212 ables _i*,_* and _dh don't get restored properly. In the future
213 we will try to implement full session saving by writing and
214 retrieving a snapshot of the memory state of IPython. But our
215 first attempts failed because of inherent limitations of
216 Python's Pickle module, so this may have to wait.
217 -[no]messages
219 Print messages which IPython collects about its startup process
220 (default on).
221 -[no]pdb
223 Automatically call the pdb debugger after every uncaught excep‐
224 tion. If you are used to debugging using pdb, this puts you
225 automatically inside of it after any call (either in IPython or
226 in code called by it) which triggers an exception which goes
227 uncaught.
228 -pydb Makes IPython use the third party "pydb" package as debugger,
230 instead of pdb. Requires that pydb is installed.
231 -[no]pprint
233 IPython can optionally use the pprint (pretty printer) module
234 for displaying results. pprint tends to give a nicer display of
235 nested data structures. If you like it, you can turn it on per‐
236 manently in your config file (default off).
237 -profile|p <name>
239 Assume that your config file is ipythonrc-<name> (looks in cur‐
240 rent dir first, then in IPYTHONDIR). This is a quick way to keep
241 and load multiple config files for different tasks, especially
242 if you use the include option of config files. You can keep a
243 basic IPYTHONDIR/ipythonrc file and then have other 'profiles'
244 which include this one and load extra things for particular
245 tasks. For example:
246 1) $HOME/.ipython/ipythonrc : load basic things you always want.
248 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-
249 related modules.
250 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
251 plotting modules.
252 Since it is possible to create an endless loop by having circu‐
254 lar file inclusions, IPython will stop if it reaches 15 recur‐
255 sive inclusions.
256 -prompt_in1|pi1 <string>
258 Specify the string used for input prompts. Note that if you are
259 using numbered prompts, the number is represented with a '\#' in
260 the string. Don't forget to quote strings with spaces embedded
261 in them. Default: 'In [\#]: '.
262 Most bash-like escapes can be used to customize IPython's
264 prompts, as well as a few additional ones which are IPython-spe‐
265 cific. All valid prompt escapes are described in detail in the
266 Customization section of the IPython HTML/PDF manual.
267 -prompt_in2|pi2 <string>
269 Similar to the previous option, but used for the continuation
270 prompts. The special sequence '\D' is similar to '\#', but with
271 all digits replaced dots (so you can have your continuation
272 prompt aligned with your input prompt). Default: ' .\D.: '
273 (note three spaces at the start for alignment with 'In [\#]').
274 -prompt_out|po <string>
276 String used for output prompts, also uses numbers like
277 prompt_in1. Default: 'Out[\#]:'.
278 -quick Start in bare bones mode (no config file loaded).
280 -rcfile <name>
282 Name of your IPython resource configuration file. normally
283 IPython loads ipythonrc (from current directory) or
284 IPYTHONDIR/ipythonrc. If the loading of your config file fails,
285 IPython starts with a bare bones configuration (no modules
286 loaded at all).
287 -[no]readline
289 Use the readline library, which is needed to support name com‐
290 pletion and command history, among other things. It is enabled
291 by default, but may cause problems for users of X/Emacs in
292 Python comint or shell buffers.
293 Note that emacs 'eterm' buffers (opened with M-x term) support
295 IPython's readline and syntax coloring fine, only 'emacs' (M-x
296 shell and C-c !) buffers do not.
297 -screen_length|sl <n>
299 Number of lines of your screen. This is used to control print‐
300 ing of very long strings. Strings longer than this number of
301 lines will be sent through a pager instead of directly printed.
302 The default value for this is 0, which means IPython will auto-
304 detect your screen size every time it needs to print certain
305 potentially long strings (this doesn't change the behavior of
306 the 'print' keyword, it's only triggered internally). If for
307 some reason this isn't working well (it needs curses support),
308 specify it yourself. Otherwise don't change the default.
309 -separate_in|si <string>
311 Separator before input prompts. Default '0.
312 -separate_out|so <string>
314 Separator before output prompts. Default: 0 (nothing).
315 -separate_out2|so2 <string>
317 Separator after output prompts. Default: 0 (nothing).
318 -nosep Shorthand for '-separate_in 0 -separate_out 0 -separate_out2 0'.
320 Simply removes all input/output separators.
321 -upgrade
323 Allows you to upgrade your IPYTHONDIR configuration when you
324 install a new version of IPython. Since new versions may
325 include new command lines options or example files, this copies
326 updated ipythonrc-type files. However, it backs up (with a .old
327 extension) all files which it overwrites so that you can merge
328 back any custimizations you might have in your personal files.
329 -Version
331 Print version information and exit.
332 -wxversion <string>
334 Select a specific version of wxPython (used in conjunction with
335 -wthread). Requires the wxversion module, part of recent
336 wxPython distributions.
337 -xmode <modename>
339 Mode for exception reporting. The valid modes are Plain, Con‐
340 text, and Verbose.
341 - Plain: similar to python's normal traceback printing.
343 - Context: prints 5 lines of context source code around each
345 line in the traceback.
346 - Verbose: similar to Context, but additionally prints the vari‐
348 ables currently visible where the exception happened (shortening
349 their strings if too long). This can potentially be very slow,
350 if you happen to have a huge data structure whose string repre‐
351 sentation is complex to compute. Your computer may appear to
352 freeze for a while with cpu usage at 100%. If this occurs, you
353 can cancel the traceback with Ctrl-C (maybe hitting it more than
354 once).
355
357 It is possible to start an IPython instance inside your own Python pro‐
358 grams. In the documentation example files there are some illustrations
359 on how to do this.
360 This feature allows you to evalutate dynamically the state of your
362 code, operate with your variables, analyze them, etc. Note however
363 that any changes you make to values while in the shell do NOT propagate
364 back to the running code, so it is safe to modify your values because
365 you won't break your code in bizarre ways by doing so.
366
368 IPython was written by Fernando Perez <fperez@colorado.edu>, based on
369 earlier code by Janko Hauser <jh@comunit.de> and Nathaniel Gray
370 <n8gray@caltech.edu>. This manual page was written by Jack Moffitt
371 <jack@xiph.org>, for the Debian project (but may be used by others).
372 November 30, 2004 IPYTHON(1)