##// END OF EJS Templates
upstream » ipython
RSS

Clone from https://github.com/ipython/ipython.git

Remove extraneous information from install document
Thomas Kluyver -
Show More
Show file before | Show file after | Hide comments
@@ -1,374 +1,180 b''
1 IPython requires Python 2.7 or ≥ 3.3.
1 IPython requires Python 2.7 or ≥ 3.3.
2
2
3 .. note::
3 .. seealso::
4
4
5 If you need to use Python 2.6 or 3.2, you can find IPython 1.x
5 `Installing Jupyter <http://jupyter.readthedocs.org/en/latest/install.html>`__
6 `here <http://archive.ipython.org/release/>`__,
6 The Notebook, nbconvert, and many other former pieces of IPython are now
7 or get it with pip::
7 part of Project Jupyter.
8
9 pip install 'ipython<2'
10
8
11
9
12 Quickstart
10 Quickstart
13 ==========
11 ==========
14
12
15 If you have :mod:`pip`,
13 If you have :mod:`pip`,
16 the quickest way to get up and running with IPython is:
14 the quickest way to get up and running with IPython is:
17
15
18 .. code-block:: bash
16 .. code-block:: bash
19
17
20 $ pip install "ipython[all]"
18 $ pip install ipython
21
19
22 This will download and install IPython and its main optional dependencies for the notebook,
20 To use IPython with notebooks or the Qt console, you should also install
23 qtconsole, tests, and other functionality.
21 ``jupyter``.
24 Some dependencies (Qt, PyQt for the QtConsole, pandoc for nbconvert) are not pip-installable,
25 and will not be pulled in by pip.
26
22
27 To run IPython's test suite, use the :command:`iptest` command:
23 To run IPython's test suite, use the :command:`iptest` command:
28
24
29 .. code-block:: bash
25 .. code-block:: bash
30
26
31 $ iptest
27 $ iptest
32
28
33
29
34 Overview
30 Overview
35 ========
31 ========
36
32
37 This document describes in detail the steps required to install IPython,
33 This document describes in detail the steps required to install IPython.
38 and its various optional dependencies.
39 For a few quick ways to get started with package managers or full Python distributions,
34 For a few quick ways to get started with package managers or full Python distributions,
40 see `the install page <http://ipython.org/install.html>`_ of the IPython website.
35 see `the install page <http://ipython.org/install.html>`_ of the IPython website.
41
36
42 IPython is organized into a number of subpackages, each of which has its own dependencies.
43 All of the subpackages come with IPython, so you don't need to download and
44 install them separately. However, to use a given subpackage, you will need to
45 install all of its dependencies.
46
47 Please let us know if you have problems installing IPython or any of its dependencies.
37 Please let us know if you have problems installing IPython or any of its dependencies.
48
38
49 IPython and most dependencies can be installed via :command:`pip`.
39 IPython and most dependencies can be installed via :command:`pip`.
50 In many scenarios, this is the simplest method of installing Python packages.
40 In many scenarios, this is the simplest method of installing Python packages.
51 More information about :mod:`pip` can be found on
41 More information about :mod:`pip` can be found on
52 `its PyPI page <http://pypi.python.org/pypi/pip>`__.
42 `its PyPI page <http://pypi.python.org/pypi/pip>`__.
53
43
54
44
55 More general information about installing Python packages can be found in
45 More general information about installing Python packages can be found in
56 `Python's documentation <http://docs.python.org>`_.
46 `Python's documentation <http://docs.python.org>`_.
57
47
58
48
59 Installing IPython itself
49 Installing IPython itself
60 =========================
50 =========================
61
51
62 Given a properly built Python, the basic interactive IPython shell will work
52 Given a properly built Python, the basic interactive IPython shell will work
63 with no external dependencies. However, some Python distributions
53 with no external dependencies. However, some Python distributions
64 (particularly on Windows and OS X), don't come with a working :mod:`readline`
54 (particularly on Windows and OS X), don't come with a working :mod:`readline`
65 module. The IPython shell will work without :mod:`readline`, but will lack
55 module. The IPython shell will work without :mod:`readline`, but will lack
66 many features that users depend on, such as tab completion and command line
56 many features that users depend on, such as tab completion and command line
67 editing. If you install IPython with :mod:`pip`,
57 editing. If you install IPython with :mod:`pip`,
68 then the appropriate :mod:`readline` for your platform will be installed.
58 then the appropriate :mod:`readline` for your platform will be installed.
69 See below for details of how to make sure you have a working :mod:`readline`.
59 See below for details of how to make sure you have a working :mod:`readline`.
70
60
71 Installation using pip
61 Installation using pip
72 ----------------------
62 ----------------------
73
63
74 If you have :mod:`pip`, the easiest way of getting IPython is:
64 If you have :mod:`pip`, the easiest way of getting IPython is:
75
65
76 .. code-block:: bash
66 .. code-block:: bash
77
67
78 $ pip install ipython
68 $ pip install ipython
79
69
80 That's it.
70 That's it.
81
71
82
72
83 Installation from source
73 Installation from source
84 ------------------------
74 ------------------------
85
75
86 If you don't want to use :command:`pip`, or don't have it installed,
76 If you don't want to use :command:`pip`, or don't have it installed,
87 grab the latest stable build of IPython from `here
77 grab the latest stable tarball of IPython `from PyPI
88 <http://ipython.org/download.html>`_. Then do the following:
78 <https://pypi.python.org/pypi/ipython>`__. Then do the following:
89
79
90 .. code-block:: bash
80 .. code-block:: bash
91
81
92 $ tar -xzf ipython.tar.gz
82 $ tar -xzf ipython.tar.gz
93 $ cd ipython
83 $ cd ipython
94 $ python setup.py install
84 $ python setup.py install
95
85
96 If you are installing to a location (like ``/usr/local``) that requires higher
86 If you are installing to a location (like ``/usr/local``) that requires higher
97 permissions, you may need to run the last command with :command:`sudo`.
87 permissions, you may need to run the last command with :command:`sudo`.
98
88
99
89
100
101 Installing the development version
90 Installing the development version
102 ----------------------------------
91 ----------------------------------
103
92
104 It is also possible to install the development version of IPython from our
93 It is also possible to install the development version of IPython from our
105 `Git <http://git-scm.com/>`_ source code repository. To do this you will
94 `Git <http://git-scm.com/>`_ source code repository. To do this you will
106 need to have Git installed on your system. Then do:
95 need to have Git installed on your system. Then do:
107
96
108 .. code-block:: bash
97 .. code-block:: bash
109
98
110 $ git clone --recursive https://github.com/ipython/ipython.git
99 $ git clone --recursive https://github.com/ipython/ipython.git
111 $ cd ipython
100 $ cd ipython
112 $ python setup.py install
101 $ python setup.py install
113
102
114 Some users want to be able to follow the development branch as it changes. If
103 Some users want to be able to follow the development branch as it changes. If
115 you have :mod:`pip`, you can replace the last step by:
104 you have :mod:`pip`, you can replace the last step by:
116
105
117 .. code-block:: bash
106 .. code-block:: bash
118
107
119 $ pip install -e .
108 $ pip install -e .
120
109
121 This creates links in the right places and installs the command line script to
110 This creates links in the right places and installs the command line script to
122 the appropriate places.
111 the appropriate places.
123
112
124 Then, if you want to update your IPython at any time, do:
113 Then, if you want to update your IPython at any time, do:
125
114
126 .. code-block:: bash
115 .. code-block:: bash
127
116
128 $ git pull
117 $ git pull
129
118
130 IPython now uses git submodules to ship its javascript dependencies. If you run
119 .. _dependencies:
131 IPython from git master, you may need to update submodules once in a while with:
132
133 .. code-block:: bash
134
135 $ git submodule update
136
137 or
138
139 .. code-block:: bash
140
141 $ python setup.py submodule
142
143 Another option is to copy `git hooks <https://github.com/ipython/ipython/tree/master/git-hooks>`_
144 to your ``./git/hooks/`` directory to ensure that your submodules are up to date on each pull.
145
120
121 Dependencies
122 ============
146
123
147 Basic optional dependencies
124 IPython relies on a number of other Python packages. Installing using a package
148 ===========================
125 manager like pip or conda will ensure the necessary packages are installed. If
126 you install manually, it's up to you to make sure dependencies are installed.
127 They're not listed here, because they may change from release to release, so a
128 static list will inevitably get out of date.
149
129
150 There are a number of basic optional dependencies that most users will want to
130 It also has one key non-Python dependency which you may need to install separately.
151 get. These are:
152
153 * readline (for command line editing, tab completion, etc.)
154 * nose (to run the IPython test suite)
155 * mock (Python < 3, also for tests)
156
157 If you are comfortable installing these things yourself, have at it, otherwise
158 read on for more details.
159
160 IPython uses several other modules, such as pexpect_ and path.py, if they are
161 installed on your system, but it can also use bundled versions from
162 :mod:`IPython.external`, so there's no need to install them separately.
163
131
164 readline
132 readline
165 --------
133 --------
166
134
167 As indicated above, on Windows, to get full functionality in the console
135 IPython's terminal interface relies on readline to provide features like tab
168 version of IPython, PyReadline is needed.
136 completion and history navigation. If you only want to use IPython as a kernel
137 for Jupyter notebooks and other frontends, you don't need readline.
138
139
140 **On Windows**, to get full console functionality, *PyReadline* is required.
169 PyReadline is a separate, Windows only implementation of readline that uses
141 PyReadline is a separate, Windows only implementation of readline that uses
170 native Windows calls through :mod:`ctypes`. The easiest way of installing
142 native Windows calls through :mod:`ctypes`. The easiest way of installing
171 PyReadline is you use the binary installer available `here
143 PyReadline is you use the binary installer available `here
172 <http://pypi.python.org/pypi/pyreadline>`__.
144 <http://pypi.python.org/pypi/pyreadline>`__.
173
145
174 On OS X, if you are using the built-in Python shipped by Apple, you will be
146 **On OS X**, if you are using the built-in Python shipped by Apple, you will be
175 missing a proper readline implementation as Apple ships instead a library called
147 missing a proper readline implementation as Apple ships instead a library called
176 ``libedit`` that provides only some of readline's functionality. While you may
148 ``libedit`` that provides only some of readline's functionality. While you may
177 find libedit sufficient, we have occasional reports of bugs with it and several
149 find libedit sufficient, we have occasional reports of bugs with it and several
178 developers who use OS X as their main environment consider libedit unacceptable
150 developers who use OS X as their main environment consider libedit unacceptable
179 for productive, regular use with IPython.
151 for productive, regular use with IPython.
180
152
181 Therefore, IPython on OS X depends on the :mod:`gnureadline` module.
153 Therefore, IPython on OS X depends on the :mod:`gnureadline` module.
182 We will *not* consider completion/history problems to be bugs for IPython if you are using libedit.
154 We will *not* consider completion/history problems to be bugs for IPython if you
155 are using libedit.
183
156
184 To get a working :mod:`readline` module on OS X, do (with :mod:`pip`
157 To get a working :mod:`readline` module on OS X, do (with :mod:`pip`
185 installed):
158 installed):
186
159
187 .. code-block:: bash
160 .. code-block:: bash
188
161
189 $ pip install gnureadline
162 $ pip install gnureadline
190
163
191 .. note::
164 .. note::
192
165
193 Other Python distributions on OS X (such as Anaconda, fink, MacPorts)
166 Other Python distributions on OS X (such as Anaconda, fink, MacPorts)
194 already have proper readline so you likely don't have to do this step.
167 already have proper readline so you likely don't have to do this step.
195
168
196 When IPython is installed with :mod:`pip`,
169 When IPython is installed with :mod:`pip`,
197 the correct readline should be installed if you specify the `terminal`
170 the correct readline should be installed if you specify the `terminal`
198 optional dependencies:
171 optional dependencies:
199
172
200 .. code-block:: bash
173 .. code-block:: bash
201
174
202 $ pip install "ipython[terminal]"
175 $ pip install "ipython[terminal]"
203
176
177 **On Linux**, readline is normally installed by default. If not, install it
178 from your system package manager. If you are compiling your own Python, make
179 sure you install the readline development headers first.
204
180
205 nose
206 ----
207
208 To run the IPython test suite you will need the :mod:`nose` package. Nose
209 provides a great way of sniffing out and running all of the IPython tests. The
210 simplest way of getting nose is to use :command:`pip`:
211
212 .. code-block:: bash
213
214 $ pip install nose
215
216 Another way of getting this is to do:
217
218 .. code-block:: bash
219
220 $ pip install "ipython[test]"
221
222 For more installation options, see the `nose website
223 <https://nose.readthedocs.org>`_.
224
225 Once you have nose installed, you can run IPython's test suite using the
226 iptest command:
227
228 .. code-block:: bash
229
230 $ iptest
231
232 Dependencies for IPython.parallel (parallel computing)
233 ======================================================
234
235 IPython's inter-process communication uses the PyZMQ_ bindings for the ZeroMQ_ messaging library.
236 This is the only dependency for :mod:`IPython.parallel`.
237
238 Shortcut:
239
240 .. code-block:: bash
241
242 pip install "ipython[parallel]"
243
244 or manual
245
246 .. code-block:: bash
247
248 pip install pyzmq
249
250 PyZMQ provides wheels for current Python on OS X and Windows, so installing pyzmq will typically not require compilation.
251
252 IPython.parallel can use SSH tunnels, which require paramiko_ on Windows.
253
254 Dependencies for the IPython Qt console
255 =======================================
256
257 pyzmq_, pygments_, PyQt_ (or PySide_)
258
259 Shortcut:
260
261 .. code-block:: bash
262
263 pip install "ipython[qtconsole]"
264
265 or manual
266
267 .. code-block:: bash
268
269 pip install pyzmq pygments
270
271 PyQt/PySide are not pip installable, so generally must be installed via system package managers (or conda).
272
273 .. _installnotebook:
274
275 Dependencies for the IPython HTML notebook
276 ==========================================
277
278 The HTML notebook is a complex web application with quite a few dependencies:
279
280 pyzmq_, jinja2_, tornado_, mistune_, jsonschema_, pygments_, terminado_
281
282 Shortcut:
283
284 .. code-block:: bash
285
286 pip install "ipython[notebook]"
287
288 or manual:
289
290 .. code-block:: bash
291
292 pip install pyzmq jinja2 tornado mistune jsonschema pygments terminado
293
294 The IPython notebook is a notebook-style web interface to IPython and can be
295 started with the command ``ipython notebook``.
296
297 MathJax
298 -------
299
300 The IPython notebook uses the MathJax_ Javascript library for rendering LaTeX
301 in web browsers. Because MathJax is large, we don't include it with
302 IPython. Normally IPython will load MathJax from a CDN, but if you have a slow
303 network connection, or want to use LaTeX without an internet connection at all,
304 you can install MathJax locally.
305
306 A quick and easy method is to install it from a python session::
307
308 python -m IPython.external.mathjax
309
310 If you need tighter configuration control, you can download your own copy
311 of MathJax from http://www.mathjax.org/download/ - use the MathJax-2.0 link.
312 When you have the file stored locally, install it with::
313
314 python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip
315
316 For unusual needs, IPython can tell you what directory it wants to find MathJax in::
317
318 python -m IPython.external.mathjax -d /some/other/mathjax
319
320 By default MathJax will be installed in your ipython directory, but you
321 can install MathJax system-wide. Please refer to the documentation
322 of :mod:`IPython.external.mathjax`
323
324 Browser Compatibility
325 ---------------------
326
327 The IPython notebook is officially supported on the following browsers:
328
329 * Chrome ≥ 13
330 * Safari ≥ 5
331 * Firefox ≥ 6
332
333 The is mainly due to the notebook's usage of WebSockets and the flexible box model.
334
335 The following browsers are unsupported:
336
337 * Safari < 5
338 * Firefox < 6
339 * Chrome < 13
340 * Opera (any): CSS issues, but execution might work
341 * Internet Explorer < 10
342 * Internet Explorer ≥ 10 (same as Opera)
343
344 Using Safari with HTTPS and an untrusted certificate is known to not work (websockets will fail).
345
346
347 Dependencies for nbconvert (converting notebooks to various formats)
348 ====================================================================
349
350 For converting markdown to formats other than HTML, nbconvert uses Pandoc_ (1.12.1 or later).
351
352 To install pandoc on Linux, you can generally use your package manager::
353
354 sudo apt-get install pandoc
355
356 On other platforms, you can get pandoc from `their website <http://johnmacfarlane.net/pandoc/installing.html>`_.
357
358
359 .. _ZeroMQ: http://www.zeromq.org
360 .. _PyZMQ: https://github.com/zeromq/pyzmq
361 .. _paramiko: https://github.com/robey/paramiko
362 .. _pygments: http://pygments.org
363 .. _pexpect: http://pexpect.readthedocs.org/en/latest/
364 .. _Jinja: http://jinja.pocoo.org
365 .. _Sphinx: http://sphinx-doc.org
366 .. _pandoc: http://johnmacfarlane.net/pandoc
367 .. _Tornado: http://www.tornadoweb.org
368 .. _MathJax: http://www.mathjax.org
369 .. _PyQt: http://www.riverbankcomputing.com/software/pyqt/intro
370 .. _PySide: http://qt-project.org/wiki/PySide
371 .. _jinja2: http://jinja.pocoo.org/
372 .. _mistune: https://github.com/lepture/mistune
373 .. _jsonschema: https://github.com/Julian/jsonschema
374 .. _terminado: https://github.com/takluyver/terminado
General Comments 0
You need to be logged in to leave comments. Login now