Show More
@@ -1,12 +1,10 b'' | |||
|
1 | 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 | |
|
6 | `here <http://archive.ipython.org/release/>`__, | |
|
7 | or get it with pip:: | |
|
8 | ||
|
9 | pip install 'ipython<2' | |
|
5 | `Installing Jupyter <http://jupyter.readthedocs.org/en/latest/install.html>`__ | |
|
6 | The Notebook, nbconvert, and many other former pieces of IPython are now | |
|
7 | part of Project Jupyter. | |
|
10 | 8 | |
|
11 | 9 | |
|
12 | 10 | Quickstart |
@@ -17,12 +15,10 b' the quickest way to get up and running with IPython is:' | |||
|
17 | 15 | |
|
18 | 16 | .. code-block:: bash |
|
19 | 17 | |
|
20 |
$ pip install |
|
|
18 | $ pip install ipython | |
|
21 | 19 | |
|
22 | This will download and install IPython and its main optional dependencies for the notebook, | |
|
23 | qtconsole, tests, and other functionality. | |
|
24 | Some dependencies (Qt, PyQt for the QtConsole, pandoc for nbconvert) are not pip-installable, | |
|
25 | and will not be pulled in by pip. | |
|
20 | To use IPython with notebooks or the Qt console, you should also install | |
|
21 | ``jupyter``. | |
|
26 | 22 | |
|
27 | 23 | To run IPython's test suite, use the :command:`iptest` command: |
|
28 | 24 | |
@@ -34,16 +30,10 b" To run IPython's test suite, use the :command:`iptest` command:" | |||
|
34 | 30 | Overview |
|
35 | 31 | ======== |
|
36 | 32 | |
|
37 |
This document describes in detail the steps required to install IPython |
|
|
38 | and its various optional dependencies. | |
|
33 | This document describes in detail the steps required to install IPython. | |
|
39 | 34 | For a few quick ways to get started with package managers or full Python distributions, |
|
40 | 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 | 37 | Please let us know if you have problems installing IPython or any of its dependencies. |
|
48 | 38 | |
|
49 | 39 | IPython and most dependencies can be installed via :command:`pip`. |
@@ -84,8 +74,8 b' Installation from source' | |||
|
84 | 74 | ------------------------ |
|
85 | 75 | |
|
86 | 76 | If you don't want to use :command:`pip`, or don't have it installed, |
|
87 |
grab the latest stable |
|
|
88 |
<http://ipython.org/ |
|
|
77 | grab the latest stable tarball of IPython `from PyPI | |
|
78 | <https://pypi.python.org/pypi/ipython>`__. Then do the following: | |
|
89 | 79 | |
|
90 | 80 | .. code-block:: bash |
|
91 | 81 | |
@@ -97,7 +87,6 b' If you are installing to a location (like ``/usr/local``) that requires higher' | |||
|
97 | 87 | permissions, you may need to run the last command with :command:`sudo`. |
|
98 | 88 | |
|
99 | 89 | |
|
100 | ||
|
101 | 90 | Installing the development version |
|
102 | 91 | ---------------------------------- |
|
103 | 92 | |
@@ -127,51 +116,34 b' Then, if you want to update your IPython at any time, do:' | |||
|
127 | 116 | |
|
128 | 117 | $ git pull |
|
129 | 118 | |
|
130 | IPython now uses git submodules to ship its javascript dependencies. If you run | |
|
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. | |
|
119 | .. _dependencies: | |
|
145 | 120 | |
|
121 | Dependencies | |
|
122 | ============ | |
|
146 | 123 | |
|
147 | Basic optional dependencies | |
|
148 | =========================== | |
|
124 | IPython relies on a number of other Python packages. Installing using a package | |
|
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 | |
|
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. | |
|
130 | It also has one key non-Python dependency which you may need to install separately. | |
|
163 | 131 | |
|
164 | 132 | readline |
|
165 | 133 | -------- |
|
166 | 134 | |
|
167 | As indicated above, on Windows, to get full functionality in the console | |
|
168 | version of IPython, PyReadline is needed. | |
|
135 | IPython's terminal interface relies on readline to provide features like tab | |
|
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 | 141 | PyReadline is a separate, Windows only implementation of readline that uses |
|
170 | 142 | native Windows calls through :mod:`ctypes`. The easiest way of installing |
|
171 | 143 | PyReadline is you use the binary installer available `here |
|
172 | 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 | 147 | missing a proper readline implementation as Apple ships instead a library called |
|
176 | 148 | ``libedit`` that provides only some of readline's functionality. While you may |
|
177 | 149 | find libedit sufficient, we have occasional reports of bugs with it and several |
@@ -179,7 +151,8 b' developers who use OS X as their main environment consider libedit unacceptable' | |||
|
179 | 151 | for productive, regular use with IPython. |
|
180 | 152 | |
|
181 | 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 |
|
|
154 | We will *not* consider completion/history problems to be bugs for IPython if you | |
|
155 | are using libedit. | |
|
183 | 156 | |
|
184 | 157 | To get a working :mod:`readline` module on OS X, do (with :mod:`pip` |
|
185 | 158 | installed): |
@@ -201,174 +174,7 b' optional dependencies:' | |||
|
201 | 174 | |
|
202 | 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