3
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
7
<html xmlns="http://www.w3.org/1999/xhtml">
9
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11
<title>Initial configuration of your environment — IPython 0.10.2 documentation</title>
13
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
14
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
16
<script type="text/javascript">
17
var DOCUMENTATION_OPTIONS = {
20
COLLAPSE_INDEX: false,
25
<script type="text/javascript" src="../_static/jquery.js"></script>
26
<script type="text/javascript" src="../_static/underscore.js"></script>
27
<script type="text/javascript" src="../_static/doctools.js"></script>
28
<link rel="top" title="IPython 0.10.2 documentation" href="../index.html" />
29
<link rel="up" title="Configuration and customization" href="index.html" />
30
<link rel="next" title="Customization of IPython" href="customization.html" />
31
<link rel="prev" title="Configuration and customization" href="index.html" />
37
<li class="right" style="margin-right: 10px">
38
<a href="../genindex.html" title="General Index"
39
accesskey="I">index</a></li>
41
<a href="../py-modindex.html" title="Python Module Index"
44
<a href="customization.html" title="Customization of IPython"
45
accesskey="N">next</a> |</li>
47
<a href="index.html" title="Configuration and customization"
48
accesskey="P">previous</a> |</li>
49
<li><a href="../index.html">IPython 0.10.2 documentation</a> »</li>
50
<li><a href="index.html" accesskey="U">Configuration and customization</a> »</li>
54
<div class="document">
55
<div class="documentwrapper">
56
<div class="bodywrapper">
59
<div class="section" id="initial-configuration-of-your-environment">
60
<span id="initial-config"></span><h1>Initial configuration of your environment<a class="headerlink" href="#initial-configuration-of-your-environment" title="Permalink to this headline">¶</a></h1>
61
<p>This section will help you set various things in your environment for
62
your IPython sessions to be as efficient as possible. All of IPython’s
63
configuration information, along with several example files, is stored
64
in a directory named by default $HOME/.ipython. You can change this by
65
defining the environment variable IPYTHONDIR, or at runtime with the
66
command line option -ipythondir.</p>
67
<p>If all goes well, the first time you run IPython it should automatically create
68
a user copy of the config directory for you, based on its builtin defaults. You
69
can look at the files it creates to learn more about configuring the
70
system. The main file you will modify to configure IPython’s behavior is called
71
ipythonrc (with a .ini extension under Windows), included for reference
72
<a class="reference internal" href="customization.html#ipythonrc"><em>here</em></a>. This file is very commented and has many variables you
73
can change to suit your taste, you can find more details <a class="reference internal" href="customization.html#customization"><em>here</em></a>. Here we discuss the basic things you will want to make sure
74
things are working properly from the beginning.</p>
75
<div class="section" id="access-to-the-python-help-system">
76
<span id="accessing-help"></span><h2>Access to the Python help system<a class="headerlink" href="#access-to-the-python-help-system" title="Permalink to this headline">¶</a></h2>
77
<p>This is true for Python in general (not just for IPython): you should have an
78
environment variable called PYTHONDOCS pointing to the directory where your
79
HTML Python documentation lives. In my system it’s
80
<tt class="file docutils literal"><span class="pre">/usr/share/doc/python-doc/html</span></tt>, check your local details or ask your
81
systems administrator.</p>
82
<p>This is the directory which holds the HTML version of the Python
83
manuals. Unfortunately it seems that different Linux distributions
84
package these files differently, so you may have to look around a bit.
85
Below I show the contents of this directory on my system for reference:</p>
86
<div class="highlight-python"><pre>[html]> ls
87
about.html dist/ icons/ lib/ python2.5.devhelp.gz whatsnew/
88
acks.html doc/ index.html mac/ ref/
89
api/ ext/ inst/ modindex.html tut/</pre>
91
<p>You should really make sure this variable is correctly set so that
92
Python’s pydoc-based help system works. It is a powerful and convenient
93
system with full access to the Python manuals and all modules accessible
95
<p>Under Windows it seems that pydoc finds the documentation automatically,
96
so no extra setup appears necessary.</p>
98
<div class="section" id="editor">
99
<h2>Editor<a class="headerlink" href="#editor" title="Permalink to this headline">¶</a></h2>
100
<p>The %edit command (and its alias %ed) will invoke the editor set in your
101
environment as EDITOR. If this variable is not set, it will default to
102
vi under Linux/Unix and to notepad under Windows. You may want to set
103
this variable properly and to a lightweight editor which doesn’t take
104
too long to start (that is, something other than a new instance of
105
Emacs). This way you can edit multi-line code quickly and with the power
106
of a real editor right inside IPython.</p>
107
<p>If you are a dedicated Emacs user, you should set up the Emacs server so
108
that new requests are handled by the original process. This means that
109
almost no time is spent in handling the request (assuming an Emacs
110
process is already running). For this to work, you need to set your
111
EDITOR environment variable to ‘emacsclient’. The code below, supplied
112
by Francois Pinard, can then be used in your .emacs file to enable the
114
<div class="highlight-python"><pre>(defvar server-buffer-clients)
115
(when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
117
(defun fp-kill-server-with-buffer-routine ()
118
(and server-buffer-clients (server-done)))
119
(add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))</pre>
121
<p>You can also set the value of this editor via the commmand-line option
122
‘-editor’ or in your ipythonrc file. This is useful if you wish to use
123
specifically for IPython an editor different from your typical default
124
(and for Windows users who tend to use fewer environment variables).</p>
126
<div class="section" id="color">
127
<h2>Color<a class="headerlink" href="#color" title="Permalink to this headline">¶</a></h2>
128
<p>The default IPython configuration has most bells and whistles turned on
129
(they’re pretty safe). But there’s one that may cause problems on some
130
systems: the use of color on screen for displaying information. This is
131
very useful, since IPython can show prompts and exception tracebacks
132
with various colors, display syntax-highlighted source code, and in
133
general make it easier to visually parse information.</p>
134
<p>The following terminals seem to handle the color sequences fine:</p>
136
<div><ul class="simple">
137
<li>Linux main text console, KDE Konsole, Gnome Terminal, E-term,
139
<li>CDE terminal (tested under Solaris). This one boldfaces light colors.</li>
140
<li>(X)Emacs buffers. See the <a class="reference internal" href="#emacs">emacs</a> section for more details on
141
using IPython with (X)Emacs.</li>
142
<li>A Windows (XP/2k) command prompt with <a class="reference external" href="https://code.launchpad.net/pyreadline">pyreadline</a>.</li>
143
<li>A Windows (XP/2k) CygWin shell. Although some users have reported
144
problems; it is not clear whether there is an issue for everyone
145
or only under specific configurations. If you have full color
146
support under cygwin, please post to the IPython mailing list so
147
this issue can be resolved for all users.</li>
150
<p>These have shown problems:</p>
152
<div><ul class="simple">
153
<li>Windows command prompt in WinXP/2k logged into a Linux machine via
155
<li>Windows native command prompt in WinXP/2k, without Gary Bishop’s
156
extensions. Once Gary’s readline library is installed, the normal
157
WinXP/2k command prompt works perfectly.</li>
160
<p>Currently the following color schemes are available:</p>
162
<div><ul class="simple">
163
<li>NoColor: uses no color escapes at all (all escapes are empty ‘’ ‘’
164
strings). This ‘scheme’ is thus fully safe to use in any terminal.</li>
165
<li>Linux: works well in Linux console type environments: dark
166
background with light fonts. It uses bright colors for
167
information, so it is difficult to read if you have a light
168
colored background.</li>
169
<li>LightBG: the basic colors are similar to those in the Linux scheme
170
but darker. It is easy to read in terminals with light backgrounds.</li>
173
<p>IPython uses colors for two main groups of things: prompts and
174
tracebacks which are directly printed to the terminal, and the object
175
introspection system which passes large sets of data through a pager.</p>
177
<div class="section" id="input-output-prompts-and-exception-tracebacks">
178
<h2>Input/Output prompts and exception tracebacks<a class="headerlink" href="#input-output-prompts-and-exception-tracebacks" title="Permalink to this headline">¶</a></h2>
179
<p>You can test whether the colored prompts and tracebacks work on your
180
system interactively by typing ‘%colors Linux’ at the prompt (use
181
‘%colors LightBG’ if your terminal has a light background). If the input
182
prompt shows garbage like:</p>
183
<div class="highlight-python"><pre>[0;32mIn [[1;32m1[0;32m]: [0;00m</pre>
185
<p>instead of (in color) something like:</p>
186
<div class="highlight-python"><pre>In [1]:</pre>
188
<p>this means that your terminal doesn’t properly handle color escape
189
sequences. You can go to a ‘no color’ mode by typing ‘%colors NoColor’.</p>
190
<p>You can try using a different terminal emulator program (Emacs users,
191
see below). To permanently set your color preferences, edit the file
192
$HOME/.ipython/ipythonrc and set the colors option to the desired value.</p>
194
<div class="section" id="object-details-types-docstrings-source-code-etc">
195
<h2>Object details (types, docstrings, source code, etc.)<a class="headerlink" href="#object-details-types-docstrings-source-code-etc" title="Permalink to this headline">¶</a></h2>
196
<p>IPython has a set of special functions for studying the objects you are working
197
with, discussed in detail <a class="reference internal" href="../interactive/reference.html#dynamic-object-info"><em>here</em></a>. But this system
198
relies on passing information which is longer than your screen through a data
199
pager, such as the common Unix less and more programs. In order to be able to
200
see this information in color, your pager needs to be properly configured. I
201
strongly recommend using less instead of more, as it seems that more simply can
202
not understand colored text correctly.</p>
203
<p>In order to configure less as your default pager, do the following:</p>
205
<div><ol class="arabic simple">
206
<li>Set the environment PAGER variable to less.</li>
207
<li>Set the environment LESS variable to -r (plus any other options
208
you always want to pass to less by default). This tells less to
209
properly interpret control sequences, which is how color
210
information is given to your terminal.</li>
213
<p>For the bash shell, add to your ~/.bashrc file the lines:</p>
214
<div class="highlight-python"><pre>export PAGER=less
217
<p>For the csh or tcsh shells, add to your ~/.cshrc file the lines:</p>
218
<div class="highlight-python"><pre>setenv PAGER less
221
<p>There is similar syntax for other Unix shells, look at your system
222
documentation for details.</p>
223
<p>If you are on a system which lacks proper data pagers (such as Windows),
224
IPython will use a very limited builtin pager.</p>
226
<div class="section" id="x-emacs-configuration">
227
<span id="emacs"></span><h2>(X)Emacs configuration<a class="headerlink" href="#x-emacs-configuration" title="Permalink to this headline">¶</a></h2>
228
<p>Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
229
currently (X)Emacs and IPython get along very well.</p>
230
<p>Important note: You will need to use a recent enough version of
231
python-mode.el, along with the file ipython.el. You can check that the
232
version you have of python-mode.el is new enough by either looking at
233
the revision number in the file itself, or asking for it in (X)Emacs via
234
M-x py-version. Versions 4.68 and newer contain the necessary fixes for
235
proper IPython support.</p>
236
<p>The file ipython.el is included with the IPython distribution, in the
237
documentation directory (where this manual resides in PDF and HTML
239
<p>Once you put these files in your Emacs path, all you need in your .emacs
241
<div class="highlight-python"><pre>(require 'ipython)</pre>
243
<p>This should give you full support for executing code snippets via
244
IPython, opening IPython as your Python shell via <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">!</span></tt>, etc.</p>
245
<p>You can customize the arguments passed to the IPython instance at startup by
246
setting the <tt class="docutils literal"><span class="pre">py-python-command-args</span></tt> variable. For example, to start always
247
in <tt class="docutils literal"><span class="pre">pylab</span></tt> mode with hardcoded light-background colors, you can use:</p>
248
<div class="highlight-python"><pre>(setq py-python-command-args '("-pylab" "-colors" "LightBG"))</pre>
250
<p>If you happen to get garbage instead of colored prompts as described in
251
the previous section, you may need to set also in your .emacs file:</p>
252
<div class="highlight-python"><pre>(setq ansi-color-for-comint-mode t)</pre>
256
<div><ul class="simple">
257
<li>There is one caveat you should be aware of: you must start the
258
IPython shell before attempting to execute any code regions via
259
<tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">|</span></tt>. Simply type C-c ! to start IPython before passing any code
260
regions to the interpreter, and you shouldn’t experience any
262
This is due to a bug in Python itself, which has been fixed for
263
Python 2.3, but exists as of Python 2.2.2 (reported as SF bug [
265
<li>The (X)Emacs support is maintained by Alexander Schmolck, so all
266
comments/requests should be directed to him through the IPython
268
<li>This code is still somewhat experimental so it’s a bit rough
269
around the edges (although in practice, it works quite well).</li>
270
<li>Be aware that if you customize py-python-command previously, this
271
value will override what ipython.el does (because loading the
272
customization variables comes later).</li>
282
<div class="sphinxsidebar">
283
<div class="sphinxsidebarwrapper">
284
<h3><a href="../index.html">Table Of Contents</a></h3>
286
<li><a class="reference internal" href="#">Initial configuration of your environment</a><ul>
287
<li><a class="reference internal" href="#access-to-the-python-help-system">Access to the Python help system</a></li>
288
<li><a class="reference internal" href="#editor">Editor</a></li>
289
<li><a class="reference internal" href="#color">Color</a></li>
290
<li><a class="reference internal" href="#input-output-prompts-and-exception-tracebacks">Input/Output prompts and exception tracebacks</a></li>
291
<li><a class="reference internal" href="#object-details-types-docstrings-source-code-etc">Object details (types, docstrings, source code, etc.)</a></li>
292
<li><a class="reference internal" href="#x-emacs-configuration">(X)Emacs configuration</a></li>
297
<h4>Previous topic</h4>
298
<p class="topless"><a href="index.html"
299
title="previous chapter">Configuration and customization</a></p>
301
<p class="topless"><a href="customization.html"
302
title="next chapter">Customization of IPython</a></p>
304
<ul class="this-page-menu">
305
<li><a href="../_sources/config/initial_config.txt"
306
rel="nofollow">Show Source</a></li>
308
<div id="searchbox" style="display: none">
309
<h3>Quick search</h3>
310
<form class="search" action="../search.html" method="get">
311
<input type="text" name="q" size="18" />
312
<input type="submit" value="Go" />
313
<input type="hidden" name="check_keywords" value="yes" />
314
<input type="hidden" name="area" value="default" />
316
<p class="searchtip" style="font-size: 90%">
317
Enter search terms or a module, class or function name.
320
<script type="text/javascript">$('#searchbox').show(0);</script>
323
<div class="clearer"></div>
325
<div class="related">
328
<li class="right" style="margin-right: 10px">
329
<a href="../genindex.html" title="General Index"
332
<a href="../py-modindex.html" title="Python Module Index"
335
<a href="customization.html" title="Customization of IPython"
338
<a href="index.html" title="Configuration and customization"
340
<li><a href="../index.html">IPython 0.10.2 documentation</a> »</li>
341
<li><a href="index.html" >Configuration and customization</a> »</li>
345
© Copyright 2008, The IPython Development Team.
346
Last updated on Apr 09, 2011.
347
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1pre.
b'\\ No newline at end of file'
added
removed
docs/dist/html/config/initial_config.html
