1.. image:: https://codecov.io/github/ipython/ipython/coverage.svg?branch=master
2    :target: https://codecov.io/github/ipython/ipython?branch=master
3
4.. image:: https://img.shields.io/pypi/v/IPython.svg
5    :target: https://pypi.python.org/pypi/ipython
6
7.. image:: https://img.shields.io/travis/ipython/ipython.svg
8    :target: https://travis-ci.org/ipython/ipython
9
10.. image:: https://www.codetriage.com/ipython/ipython/badges/users.svg
11    :target: https://www.codetriage.com/ipython/ipython/
12
13.. image:: https://raster.shields.io/badge/Follows-NEP29-brightgreen.png
14    :target: https://numpy.org/neps/nep-0029-deprecation_policy.html
15
16
17===========================================
18 IPython: Productive Interactive Computing
19===========================================
20
21Overview
22========
23
24Welcome to IPython.  Our full documentation is available on `ipython.readthedocs.io
25<https://ipython.readthedocs.io/en/stable/>`_ and contains information on how to install, use, and
26contribute to the project.
27
28**IPython versions and Python Support**
29
30Starting with IPython 7.10, IPython follows `NEP 29 <https://numpy.org/neps/nep-0029-deprecation_policy.html>`_
31
32**IPython 7.17+** requires Python version 3.7 and above.
33
34**IPython 7.10+** requires Python version 3.6 and above.
35
36**IPython 7.0** requires Python version 3.5 and above.
37
38**IPython 6.x** requires Python version 3.3 and above.
39
40**IPython 5.x LTS** is the compatible release for Python 2.7.
41If you require Python 2 support, you **must** use IPython 5.x LTS. Please
42update your project configurations and requirements as necessary.
43
44
45The Notebook, Qt console and a number of other pieces are now parts of *Jupyter*.
46See the `Jupyter installation docs <https://jupyter.readthedocs.io/en/latest/install.html>`__
47if you want to use these.
48
49
50
51
52Development and Instant running
53===============================
54
55You can find the latest version of the development documentation on `readthedocs
56<https://ipython.readthedocs.io/en/latest/>`_.
57
58You can run IPython from this directory without even installing it system-wide
59by typing at the terminal::
60
61   $ python -m IPython
62
63Or see the `development installation docs
64<https://ipython.readthedocs.io/en/latest/install/install.html#installing-the-development-version>`_
65for the latest revision on read the docs.
66
67Documentation and installation instructions for older version of IPython can be
68found on the `IPython website <https://ipython.org/documentation.html>`_
69
70
71
72IPython requires Python version 3 or above
73==========================================
74
75Starting with version 6.0, IPython does not support Python 2.7, 3.0, 3.1, or
763.2.
77
78For a version compatible with Python 2.7, please install the 5.x LTS Long Term
79Support version.
80
81If you are encountering this error message you are likely trying to install or
82use IPython from source. You need to checkout the remote 5.x branch. If you are
83using git the following should work::
84
85  $ git fetch origin
86  $ git checkout 5.x
87
88If you encounter this error message with a regular install of IPython, then you
89likely need to update your package manager, for example if you are using `pip`
90check the version of pip with::
91
92  $ pip --version
93
94You will need to update pip to the version 9.0.1 or greater. If you are not using
95pip, please inquiry with the maintainers of the package for your package
96manager.
97
98For more information see one of our blog posts:
99
100    https://blog.jupyter.org/release-of-ipython-5-0-8ce60b8d2e8e
101
102As well as the following Pull-Request for discussion:
103
104    https://github.com/ipython/ipython/pull/9900
105
106This error does also occur if you are invoking ``setup.py`` directly – which you
107should not – or are using ``easy_install`` If this is the case, use ``pip
108install .`` instead of ``setup.py install`` , and ``pip install -e .`` instead
109of ``setup.py develop`` If you are depending on IPython as a dependency you may
110also want to have a conditional dependency on IPython depending on the Python
111version::
112
113    install_req = ['ipython']
114    if sys.version_info[0] < 3 and 'bdist_wheel' not in sys.argv:
115        install_req.remove('ipython')
116        install_req.append('ipython<6')
117
118    setup(
119        ...
120        install_requires=install_req
121    )
122
123Alternatives to IPython
124=======================
125
126IPython may not be to your taste; if that's the case there might be similar
127project that you might want to use:
128
129- the classic Python REPL.
130- `bpython <https://bpython-interpreter.org/>`_
131- `mypython <https://www.asmeurer.com/mypython/>`_
132- `ptpython and ptipython <https://pypi.org/project/ptpython/>`
133- `xonsh <https://xon.sh/>`
134
135Ignoring commits with git blame.ignoreRevsFile
136==============================================
137
138As of git 2.23, it is possible to make formatting changes without breaking
139``git blame``. See the `git documentation
140<https://git-scm.com/docs/git-config#Documentation/git-config.txt-blameignoreRevsFile>`_
141for more details.
142
143To use this feature you must:
144
145- Install git >= 2.23
146- Configure your local git repo by running:
147   - POSIX: ``tools\configure-git-blame-ignore-revs.sh``
148   - Windows:  ``tools\configure-git-blame-ignore-revs.bat``
149