Installing Cartopy
==================

Pre-built binaries
------------------

The easiest route to installing cartopy is through 
`Conda <https://conda.io/miniconda.html>`_. For all platforms
installing cartopy can be done with::

    conda install -c conda-forge cartopy

Additional options include:
 * `Enthought Canopy <https://www.enthought.com/product/canopy/>`_.
 * Christoph Gohlke (https://www.lfd.uci.edu/~gohlke/pythonlibs/)
   maintains unofficial Windows binaries of cartopy.
 * `OSGeo Live <https://live.osgeo.org>`_.


Building from source
--------------------

The latest release of Cartopy is available from
https://github.com/SciTools/Cartopy.

Once you have satisfied the requirements detailed below, simply run::

    python setup.py install

For non-standard locations, additional build lib & include paths
can be provided as per-usual at build_ext phase::

    python setup.py build_ext -I/path/to/include -L/path/to/lib
    python setup.py install


Requirements
~~~~~~~~~~~~
These external packages are required to install Cartopy or gain access to
significant Cartopy functionality.

Many of these packages are available in Linux package managers
such as aptitude and yum. For example, it may be possible to install
Numpy using::

    apt-get install python-numpy

If you are installing dependencies with a package manager on Linux,
you may need to install the development packages (look for a "-dev"
suffix) in addition to the core packages.

Many of these dependencies are built as part of Cartopy's conda distribution.
The recipes for these can be found at https://github.com/conda-forge/feedstocks.


**Python** 2.7 or later (https://www.python.org/)
    Cartopy requires Python 2.7 or later.

**Cython** 0.28 or later (https://pypi.python.org/pypi/Cython/)

**NumPy** 1.10 or later (https://numpy.org/)
    Python package for scientific computing including a powerful N-dimensional
    array object.

**GEOS** 3.3.3 or later (https://trac.osgeo.org/geos/)
    GEOS is an API of spatial predicates and functions for processing geometry
    written in C++.

**Shapely** 1.5.6 or later (https://github.com/Toblerity/Shapely)
    Python package for the manipulation and analysis of planar geometric
    objects.

**pyshp** 2.0 or later (https://pypi.python.org/pypi/pyshp)
    Pure Python read/write support for ESRI Shapefile format.

**PROJ** 4.9.0 or later (https://proj4.org/)
    Cartographic Projections library.

**six** 1.3.0 or later (https://pypi.python.org/pypi/six)
    Python 2 and 3 compatibility.


Optional Dependencies
~~~~~~~~~~~~~~~~~~~~~
These are optional packages which you may want to install to enable
additional Cartopy functionality.

**Matplotlib** 1.5.1 or later (https://matplotlib.org/)
    Python package for 2D plotting.  This package is required for any
    graphical capability.

**GDAL** version 1.10.0 (https://gdal.org/)
    GDAL is a translator library for raster and vector geospatial data formats,
    which has powerful data transformation and processing capabilities.

**Pillow** 1.7.8 or later (https://pypi.python.org/pypi/Pillow/2.3.0)
    Popular fork of PythonImagingLibrary.

**pyepsg** 0.4.0 or later (https://github.com/rhattersley/pyepsg)
    A simple Python interface to https://epsg.io

**pykdtree** 1.2.2 or later (https://github.com/storpipfugl/pykdtree)
    Fast kd-tree implementation in Python; used for faster warping of images in
    preference to SciPy.

**SciPy** 0.10 or later (https://www.scipy.org/)
    Python package for scientific computing.

**OWSLib** 0.8.7 (https://pypi.python.org/pypi/OWSLib)
     Python package for client programming with Open Geospatial Consortium
     (OGC) web service.  Gives access to cartopy ogc clients.

**Fiona** 1.0 or later (https://github.com/Toblerity/Fiona)
    Python package for reading shapefiles faster than the default (pyshp).


Testing Dependencies
~~~~~~~~~~~~~~~~~~~~
These packages are required for the full Cartopy test suite to run.

**filelock** (https://filelock.readthedocs.io/)
    A platform independent file lock for Python.

**mock** 1.0.1 (https://pypi.python.org/pypi/mock/)
    Python mocking and patching package for testing. Note that this package
    is only required to support the Cartopy unit tests.

**pytest** 3.1.0 or later (https://docs.pytest.org/en/latest/)
    Python package for software testing.

**pep8** 1.3.3 or later (https://pypi.python.org/pypi/pep8)
    Python package for software testing.
