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