From 528f94ca0694989cee01c17a97276e29521fac51 Mon Sep 17 00:00:00 2001 From: lexual Date: Sat, 26 Jul 2014 20:15:03 +1000 Subject: [PATCH] Docs: improve installation instructions, recommend Anaconda. --- doc/source/install.rst | 314 ++++++++++++++++++++++++++++------------- 1 file changed, 214 insertions(+), 100 deletions(-) diff --git a/doc/source/install.rst b/doc/source/install.rst index fe56b53d7cb82..c30a086295f00 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -2,64 +2,250 @@ .. currentmodule:: pandas -************ +============ Installation -************ +============ -You have the option to install an `official release -`__ or to build the `development version -`__. If you choose to install from source and -are running Windows, you will have to ensure that you have a compatible C -compiler (MinGW or Visual Studio) installed. `How-to install MinGW on Windows -`__ +The easiest way for the majority of users to install pandas is to install it +as part of the `Anaconda `__ distribution, a +cross platform distribution for data analysis and scientific computing. +This is the recommended installation method for most users. + +Instructions for installing from source, +`PyPI `__, various Linux distributions, or a +`development version `__ are also provided. Python version support -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- Officially Python 2.6, 2.7, 3.2, 3.3, and 3.4. +Installing pandas +----------------- + +Trying out pandas, no installation required! +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The easiest way to start experimenting with pandas doesn't involve installing +pandas at all. + +`Wakari `__ is a free service that provides a hosted +`IPython Notebook `__ service in the cloud. + +Simply create an account, and have access to pandas from within your brower via +an `IPython Notebook `__ in a few minutes. + +Installing pandas with Anaconda +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Installing pandas and the rest of the `NumPy `__ and +`SciPy `__ stack can be a little +difficult for inexperienced users. + +The simplest way to install not only pandas, but Python and the most popular +packages that make up the `SciPy `__ stack +(`IPython `__, `NumPy `__, +`Matplotlib `__, ...) is with +`Anaconda `__, a cross-platform +(Linux, Mac OS X, Windows) Python distribution for data analytics and +scientific computing. + +After running a simple installer, the user will have access to pandas and the +rest of the `SciPy `__ stack without needing to install +anything else, and without needing to wait for any software to be compiled. + +Installation instructions for `Anaconda `__ +`can be found here `__. + +A full list of the packages available as part of the +`Anaconda `__ distribution +`can be found here `__. + +An additional advantage of installing with Anaconda is that you don't require +admin rights to install it, it will install in the user's home directory, and +this also makes it trivial to delete Anaconda at a later date (just delete +that folder). + +Installing pandas with Miniconda +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The previous section outlined how to get pandas installed as part of the +`Anaconda `__ distribution. +However this approach means you will install well over one hundred packages +and involves downloading the installer which is a few hundred megabytes in size. + +If you want to have more control on which packages, or have a limited internet +bandwidth, then installing pandas with +`Miniconda `__ may be a better solution. + +`Conda `__ is the package manager that the +`Anaconda `__ distribution is built upon. +It is a package manager that is both cross-platform and language agnostic +(it can play a similar role to a pip and virtualenv combination). + +`Miniconda `__ allows you to create a +minimal self contained Python installation, and then use the +`Conda `__ command to install additional packages. + +First you will need `Conda `__ to be installed and +downloading and running the `Miniconda +`__ +will do this for you. The installer +`can be found here `__ + +The next step is to create a new conda environment (these are analogous to a +virtualenv but they also allow you to specify precisely which Python version +to install also). Run the following commands from a terminal window:: + + conda create -n name_of_my_env python + +This will create a minimal environment with only Python installed in it. +To put your self inside this environment run:: + + source activate name_of_my_env + +On Windows the command is:: -Binary installers -~~~~~~~~~~~~~~~~~ + activate name_of_my_env -.. _all-platforms: +The final step required is to install pandas. This can be done with the +following command:: -All platforms -_____________ + conda install pandas -Stable installers available on `PyPI `__ +To install a specific pandas version:: -Preliminary builds and installers on the `pandas download page `__ . + conda install pandas=0.13.1 -Overview -___________ +To install other packages, IPython for example:: + + conda install ipython + +To install the full `Anaconda `__ +distribution:: + + conda install anaconda + +If you require any packages that are available to pip but not conda, simply +install pip, and use pip to install these packages:: + + conda install pip + pip install django + +Installing from PyPI +~~~~~~~~~~~~~~~~~~~~ + +pandas can be installed via pip from +`PyPI `__. + +:: + + pip install pandas + +This will likely require the installation of a number of dependencies, +including NumPy, will require a compiler to compile required bits of code, +and can take a few minutes to complete. + +Installing using your Linux distribution's package manager. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: - :header: "Platform", "Distribution", "Status", "Download / Repository Link", "Install method" - :widths: 10, 10, 10, 20, 50 + :header: "Distribution", "Status", "Download / Repository Link", "Install method" + :widths: 10, 10, 20, 50 + + + Debian, stable, `official Debian repository `__ , ``sudo apt-get install python-pandas`` + Debian & Ubuntu, unstable (latest packages), `NeuroDebian `__ , ``sudo apt-get install python-pandas`` + Ubuntu, stable, `official Ubuntu repository `__ , ``sudo apt-get install python-pandas`` + Ubuntu, unstable (daily builds), `PythonXY PPA `__; activate by: ``sudo add-apt-repository ppa:pythonxy/pythonxy-devel && sudo apt-get update``, ``sudo apt-get install python-pandas`` + OpenSuse & Fedora, stable, `OpenSuse Repository `__ , ``zypper in python-pandas`` + + + + + + + + - Windows, all, stable, :ref:`all-platforms`, ``pip install pandas`` - Mac, all, stable, :ref:`all-platforms`, ``pip install pandas`` - Linux, Debian, stable, `official Debian repository `__ , ``sudo apt-get install python-pandas`` - Linux, Debian & Ubuntu, unstable (latest packages), `NeuroDebian `__ , ``sudo apt-get install python-pandas`` - Linux, Ubuntu, stable, `official Ubuntu repository `__ , ``sudo apt-get install python-pandas`` - Linux, Ubuntu, unstable (daily builds), `PythonXY PPA `__; activate by: ``sudo add-apt-repository ppa:pythonxy/pythonxy-devel && sudo apt-get update``, ``sudo apt-get install python-pandas`` - Linux, OpenSuse & Fedora, stable, `OpenSuse Repository `__ , ``zypper in python-pandas`` +Installing from source +~~~~~~~~~~~~~~~~~~~~~~ +.. note:: + Installing from the git repository requires a recent installation of `Cython + `__ as the cythonized C sources are no longer checked + into source control. Released source distributions will contain the built C + files. I recommend installing the latest Cython via ``easy_install -U + Cython`` +The source code is hosted at http://github.com/pydata/pandas, it can be checked +out using git and compiled / installed like so: +:: + git clone git://github.com/pydata/pandas.git + cd pandas + python setup.py install +Make sure you have Cython installed when installing from the repository, +rather then a tarball or pypi. +On Windows, I suggest installing the MinGW compiler suite following the +directions linked to above. Once configured property, run the following on the +command line: + +:: + + python setup.py build --compiler=mingw32 + python setup.py install + +Note that you will not be able to import pandas if you open an interpreter in +the source directory unless you build the C extensions in place: + +:: + + python setup.py build_ext --inplace + +The most recent version of MinGW (any installer dated after 2011-08-03) +has removed the '-mno-cygwin' option but Distutils has not yet been updated to +reflect that. Thus, you may run into an error like "unrecognized command line +option '-mno-cygwin'". Until the bug is fixed in Distutils, you may need to +install a slightly older version of MinGW (2011-08-02 installer). + +Running the test suite +~~~~~~~~~~~~~~~~~~~~~~ + +pandas is equipped with an exhaustive set of unit tests covering about 97% of +the codebase as of this writing. To run it on your machine to verify that +everything is working (and you have all of the dependencies, soft and hard, +installed), make sure you have `nose +`__ and run: +:: + $ nosetests pandas + .......................................................................... + .......................S.................................................. + .......................................................................... + .......................................................................... + .......................................................................... + .......................................................................... + .......................................................................... + .......................................................................... + .......................................................................... + .......................................................................... + .................S........................................................ + .... + ---------------------------------------------------------------------- + Ran 818 tests in 21.631s + OK (SKIP=2) Dependencies -~~~~~~~~~~~~ +------------ * `NumPy `__: 1.6.1 or higher * `python-dateutil `__ 1.5 @@ -165,75 +351,3 @@ Optional Dependencies distribution like `Enthought Canopy `__ may be worth considering. -Installing from source -~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - Installing from the git repository requires a recent installation of `Cython - `__ as the cythonized C sources are no longer checked - into source control. Released source distributions will contain the built C - files. I recommend installing the latest Cython via ``easy_install -U - Cython`` - -The source code is hosted at http://github.com/pydata/pandas, it can be checked -out using git and compiled / installed like so: - -:: - - git clone git://github.com/pydata/pandas.git - cd pandas - python setup.py install - -Make sure you have Cython installed when installing from the repository, -rather then a tarball or pypi. - -On Windows, I suggest installing the MinGW compiler suite following the -directions linked to above. Once configured property, run the following on the -command line: - -:: - - python setup.py build --compiler=mingw32 - python setup.py install - -Note that you will not be able to import pandas if you open an interpreter in -the source directory unless you build the C extensions in place: - -:: - - python setup.py build_ext --inplace - -The most recent version of MinGW (any installer dated after 2011-08-03) -has removed the '-mno-cygwin' option but Distutils has not yet been updated to -reflect that. Thus, you may run into an error like "unrecognized command line -option '-mno-cygwin'". Until the bug is fixed in Distutils, you may need to -install a slightly older version of MinGW (2011-08-02 installer). - -Running the test suite -~~~~~~~~~~~~~~~~~~~~~~ - -pandas is equipped with an exhaustive set of unit tests covering about 97% of -the codebase as of this writing. To run it on your machine to verify that -everything is working (and you have all of the dependencies, soft and hard, -installed), make sure you have `nose -`__ and run: - -:: - - $ nosetests pandas - .......................................................................... - .......................S.................................................. - .......................................................................... - .......................................................................... - .......................................................................... - .......................................................................... - .......................................................................... - .......................................................................... - .......................................................................... - .......................................................................... - .................S........................................................ - .... - ---------------------------------------------------------------------- - Ran 818 tests in 21.631s - - OK (SKIP=2)