Skip to content

Commit 381a289

Browse files
jrebackjreback
committed
Merge pull request #7849 from lexual/docs_install_conda_wakari
Docs: improve installation instructions, recommend Anaconda.
2 parents 4f47e6b + 528f94c commit 381a289

File tree

1 file changed

+214
-100
lines changed

1 file changed

+214
-100
lines changed

‎doc/source/install.rst

+214-100
Original file line numberDiff line numberDiff line change
@@ -2,64 +2,250 @@
22

33
.. currentmodule:: pandas
44

5-
************
5+
============
66
Installation
7-
************
7+
============
88

9-
You have the option to install an `official release
10-
<http://pypi.python.org/pypi/pandas>`__ or to build the `development version
11-
<http://github.com/pydata/pandas>`__. If you choose to install from source and
12-
are running Windows, you will have to ensure that you have a compatible C
13-
compiler (MinGW or Visual Studio) installed. `How-to install MinGW on Windows
14-
<http://docs.cython.org/src/tutorial/appendix.html>`__
9+
The easiest way for the majority of users to install pandas is to install it
10+
as part of the `Anaconda <http://docs.continuum.io/anaconda/>`__ distribution, a
11+
cross platform distribution for data analysis and scientific computing.
12+
This is the recommended installation method for most users.
13+
14+
Instructions for installing from source,
15+
`PyPI <http://pypi.python.org/pypi/pandas>`__, various Linux distributions, or a
16+
`development version <http://github.com/pydata/pandas>`__ are also provided.
1517

1618
Python version support
17-
~~~~~~~~~~~~~~~~~~~~~~
19+
----------------------
1820

1921
Officially Python 2.6, 2.7, 3.2, 3.3, and 3.4.
2022

23+
Installing pandas
24+
-----------------
25+
26+
Trying out pandas, no installation required!
27+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
28+
29+
The easiest way to start experimenting with pandas doesn't involve installing
30+
pandas at all.
31+
32+
`Wakari <https://wakari.io>`__ is a free service that provides a hosted
33+
`IPython Notebook <http://ipython.org/notebook.html>`__ service in the cloud.
34+
35+
Simply create an account, and have access to pandas from within your brower via
36+
an `IPython Notebook <http://ipython.org/notebook.html>`__ in a few minutes.
37+
38+
Installing pandas with Anaconda
39+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40+
41+
Installing pandas and the rest of the `NumPy <http://www.numpy.org/>`__ and
42+
`SciPy <http://www.scipy.org/>`__ stack can be a little
43+
difficult for inexperienced users.
44+
45+
The simplest way to install not only pandas, but Python and the most popular
46+
packages that make up the `SciPy <http://www.scipy.org/>`__ stack
47+
(`IPython <http://ipython.org/>`__, `NumPy <http://www.numpy.org/>`__,
48+
`Matplotlib <http://matplotlib.org/>`__, ...) is with
49+
`Anaconda <http://docs.continuum.io/anaconda/>`__, a cross-platform
50+
(Linux, Mac OS X, Windows) Python distribution for data analytics and
51+
scientific computing.
52+
53+
After running a simple installer, the user will have access to pandas and the
54+
rest of the `SciPy <http://www.scipy.org/>`__ stack without needing to install
55+
anything else, and without needing to wait for any software to be compiled.
56+
57+
Installation instructions for `Anaconda <http://docs.continuum.io/anaconda/>`__
58+
`can be found here <http://docs.continuum.io/anaconda/install.html>`__.
59+
60+
A full list of the packages available as part of the
61+
`Anaconda <http://docs.continuum.io/anaconda/>`__ distribution
62+
`can be found here <http://docs.continuum.io/anaconda/pkg-docs.html>`__.
63+
64+
An additional advantage of installing with Anaconda is that you don't require
65+
admin rights to install it, it will install in the user's home directory, and
66+
this also makes it trivial to delete Anaconda at a later date (just delete
67+
that folder).
68+
69+
Installing pandas with Miniconda
70+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71+
72+
The previous section outlined how to get pandas installed as part of the
73+
`Anaconda <http://docs.continuum.io/anaconda/>`__ distribution.
74+
However this approach means you will install well over one hundred packages
75+
and involves downloading the installer which is a few hundred megabytes in size.
76+
77+
If you want to have more control on which packages, or have a limited internet
78+
bandwidth, then installing pandas with
79+
`Miniconda <http://conda.pydata.org/miniconda.html>`__ may be a better solution.
80+
81+
`Conda <http://conda.pydata.org/docs/>`__ is the package manager that the
82+
`Anaconda <http://docs.continuum.io/anaconda/>`__ distribution is built upon.
83+
It is a package manager that is both cross-platform and language agnostic
84+
(it can play a similar role to a pip and virtualenv combination).
85+
86+
`Miniconda <http://conda.pydata.org/miniconda.html>`__ allows you to create a
87+
minimal self contained Python installation, and then use the
88+
`Conda <http://conda.pydata.org/docs/>`__ command to install additional packages.
89+
90+
First you will need `Conda <http://conda.pydata.org/docs/>`__ to be installed and
91+
downloading and running the `Miniconda
92+
<http://conda.pydata.org/miniconda.html>`__
93+
will do this for you. The installer
94+
`can be found here <http://conda.pydata.org/miniconda.html>`__
95+
96+
The next step is to create a new conda environment (these are analogous to a
97+
virtualenv but they also allow you to specify precisely which Python version
98+
to install also). Run the following commands from a terminal window::
99+
100+
conda create -n name_of_my_env python
101+
102+
This will create a minimal environment with only Python installed in it.
103+
To put your self inside this environment run::
104+
105+
source activate name_of_my_env
106+
107+
On Windows the command is::
21108

22-
Binary installers
23-
~~~~~~~~~~~~~~~~~
109+
activate name_of_my_env
24110

25-
.. _all-platforms:
111+
The final step required is to install pandas. This can be done with the
112+
following command::
26113

27-
All platforms
28-
_____________
114+
conda install pandas
29115

30-
Stable installers available on `PyPI <http://pypi.python.org/pypi/pandas>`__
116+
To install a specific pandas version::
31117

32-
Preliminary builds and installers on the `pandas download page <http://pandas.pydata.org/getpandas.html>`__ .
118+
conda install pandas=0.13.1
33119

34-
Overview
35-
___________
120+
To install other packages, IPython for example::
121+
122+
conda install ipython
123+
124+
To install the full `Anaconda <http://docs.continuum.io/anaconda/>`__
125+
distribution::
126+
127+
conda install anaconda
128+
129+
If you require any packages that are available to pip but not conda, simply
130+
install pip, and use pip to install these packages::
131+
132+
conda install pip
133+
pip install django
134+
135+
Installing from PyPI
136+
~~~~~~~~~~~~~~~~~~~~
137+
138+
pandas can be installed via pip from
139+
`PyPI <http://pypi.python.org/pypi/pandas>`__.
140+
141+
::
142+
143+
pip install pandas
144+
145+
This will likely require the installation of a number of dependencies,
146+
including NumPy, will require a compiler to compile required bits of code,
147+
and can take a few minutes to complete.
148+
149+
Installing using your Linux distribution's package manager.
150+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36151

37152

38153

39154
.. csv-table::
40-
:header: "Platform", "Distribution", "Status", "Download / Repository Link", "Install method"
41-
:widths: 10, 10, 10, 20, 50
155+
:header: "Distribution", "Status", "Download / Repository Link", "Install method"
156+
:widths: 10, 10, 20, 50
157+
158+
159+
Debian, stable, `official Debian repository <http://packages.debian.org/search?keywords=pandas&searchon=names&suite=all&section=all>`__ , ``sudo apt-get install python-pandas``
160+
Debian & Ubuntu, unstable (latest packages), `NeuroDebian <http://neuro.debian.net/index.html#how-to-use-this-repository>`__ , ``sudo apt-get install python-pandas``
161+
Ubuntu, stable, `official Ubuntu repository <http://packages.ubuntu.com/search?keywords=pandas&searchon=names&suite=all&section=all>`__ , ``sudo apt-get install python-pandas``
162+
Ubuntu, unstable (daily builds), `PythonXY PPA <https://code.launchpad.net/~pythonxy/+archive/pythonxy-devel>`__; activate by: ``sudo add-apt-repository ppa:pythonxy/pythonxy-devel && sudo apt-get update``, ``sudo apt-get install python-pandas``
163+
OpenSuse & Fedora, stable, `OpenSuse Repository <http://software.opensuse.org/package/python-pandas?search_term=pandas>`__ , ``zypper in python-pandas``
164+
165+
166+
167+
168+
169+
170+
171+
42172

43173

44-
Windows, all, stable, :ref:`all-platforms`, ``pip install pandas``
45-
Mac, all, stable, :ref:`all-platforms`, ``pip install pandas``
46-
Linux, Debian, stable, `official Debian repository <http://packages.debian.org/search?keywords=pandas&searchon=names&suite=all&section=all>`__ , ``sudo apt-get install python-pandas``
47-
Linux, Debian & Ubuntu, unstable (latest packages), `NeuroDebian <http://neuro.debian.net/index.html#how-to-use-this-repository>`__ , ``sudo apt-get install python-pandas``
48-
Linux, Ubuntu, stable, `official Ubuntu repository <http://packages.ubuntu.com/search?keywords=pandas&searchon=names&suite=all&section=all>`__ , ``sudo apt-get install python-pandas``
49-
Linux, Ubuntu, unstable (daily builds), `PythonXY PPA <https://code.launchpad.net/~pythonxy/+archive/pythonxy-devel>`__; activate by: ``sudo add-apt-repository ppa:pythonxy/pythonxy-devel && sudo apt-get update``, ``sudo apt-get install python-pandas``
50-
Linux, OpenSuse & Fedora, stable, `OpenSuse Repository <http://software.opensuse.org/package/python-pandas?search_term=pandas>`__ , ``zypper in python-pandas``
174+
Installing from source
175+
~~~~~~~~~~~~~~~~~~~~~~
176+
.. note::
51177

178+
Installing from the git repository requires a recent installation of `Cython
179+
<http://cython.org>`__ as the cythonized C sources are no longer checked
180+
into source control. Released source distributions will contain the built C
181+
files. I recommend installing the latest Cython via ``easy_install -U
182+
Cython``
52183

184+
The source code is hosted at http://github.com/pydata/pandas, it can be checked
185+
out using git and compiled / installed like so:
53186

187+
::
54188

189+
git clone git://github.com/pydata/pandas.git
190+
cd pandas
191+
python setup.py install
55192

193+
Make sure you have Cython installed when installing from the repository,
194+
rather then a tarball or pypi.
56195

196+
On Windows, I suggest installing the MinGW compiler suite following the
197+
directions linked to above. Once configured property, run the following on the
198+
command line:
199+
200+
::
201+
202+
python setup.py build --compiler=mingw32
203+
python setup.py install
204+
205+
Note that you will not be able to import pandas if you open an interpreter in
206+
the source directory unless you build the C extensions in place:
207+
208+
::
209+
210+
python setup.py build_ext --inplace
211+
212+
The most recent version of MinGW (any installer dated after 2011-08-03)
213+
has removed the '-mno-cygwin' option but Distutils has not yet been updated to
214+
reflect that. Thus, you may run into an error like "unrecognized command line
215+
option '-mno-cygwin'". Until the bug is fixed in Distutils, you may need to
216+
install a slightly older version of MinGW (2011-08-02 installer).
217+
218+
Running the test suite
219+
~~~~~~~~~~~~~~~~~~~~~~
220+
221+
pandas is equipped with an exhaustive set of unit tests covering about 97% of
222+
the codebase as of this writing. To run it on your machine to verify that
223+
everything is working (and you have all of the dependencies, soft and hard,
224+
installed), make sure you have `nose
225+
<http://readthedocs.org/docs/nose/en/latest/>`__ and run:
57226

227+
::
58228

229+
$ nosetests pandas
230+
..........................................................................
231+
.......................S..................................................
232+
..........................................................................
233+
..........................................................................
234+
..........................................................................
235+
..........................................................................
236+
..........................................................................
237+
..........................................................................
238+
..........................................................................
239+
..........................................................................
240+
.................S........................................................
241+
....
242+
----------------------------------------------------------------------
243+
Ran 818 tests in 21.631s
59244

245+
OK (SKIP=2)
60246

61247
Dependencies
62-
~~~~~~~~~~~~
248+
------------
63249

64250
* `NumPy <http://www.numpy.org>`__: 1.6.1 or higher
65251
* `python-dateutil <http://labix.org/python-dateutil>`__ 1.5
@@ -165,75 +351,3 @@ Optional Dependencies
165351
distribution like `Enthought Canopy
166352
<http://enthought.com/products/canopy>`__ may be worth considering.
167353

168-
Installing from source
169-
~~~~~~~~~~~~~~~~~~~~~~
170-
.. note::
171-
172-
Installing from the git repository requires a recent installation of `Cython
173-
<http://cython.org>`__ as the cythonized C sources are no longer checked
174-
into source control. Released source distributions will contain the built C
175-
files. I recommend installing the latest Cython via ``easy_install -U
176-
Cython``
177-
178-
The source code is hosted at http://github.com/pydata/pandas, it can be checked
179-
out using git and compiled / installed like so:
180-
181-
::
182-
183-
git clone git://github.com/pydata/pandas.git
184-
cd pandas
185-
python setup.py install
186-
187-
Make sure you have Cython installed when installing from the repository,
188-
rather then a tarball or pypi.
189-
190-
On Windows, I suggest installing the MinGW compiler suite following the
191-
directions linked to above. Once configured property, run the following on the
192-
command line:
193-
194-
::
195-
196-
python setup.py build --compiler=mingw32
197-
python setup.py install
198-
199-
Note that you will not be able to import pandas if you open an interpreter in
200-
the source directory unless you build the C extensions in place:
201-
202-
::
203-
204-
python setup.py build_ext --inplace
205-
206-
The most recent version of MinGW (any installer dated after 2011-08-03)
207-
has removed the '-mno-cygwin' option but Distutils has not yet been updated to
208-
reflect that. Thus, you may run into an error like "unrecognized command line
209-
option '-mno-cygwin'". Until the bug is fixed in Distutils, you may need to
210-
install a slightly older version of MinGW (2011-08-02 installer).
211-
212-
Running the test suite
213-
~~~~~~~~~~~~~~~~~~~~~~
214-
215-
pandas is equipped with an exhaustive set of unit tests covering about 97% of
216-
the codebase as of this writing. To run it on your machine to verify that
217-
everything is working (and you have all of the dependencies, soft and hard,
218-
installed), make sure you have `nose
219-
<http://readthedocs.org/docs/nose/en/latest/>`__ and run:
220-
221-
::
222-
223-
$ nosetests pandas
224-
..........................................................................
225-
.......................S..................................................
226-
..........................................................................
227-
..........................................................................
228-
..........................................................................
229-
..........................................................................
230-
..........................................................................
231-
..........................................................................
232-
..........................................................................
233-
..........................................................................
234-
.................S........................................................
235-
....
236-
----------------------------------------------------------------------
237-
Ran 818 tests in 21.631s
238-
239-
OK (SKIP=2)

0 commit comments

Comments
 (0)