INSTALL

Installation
============

Conda pre-built binaries
------------------------

The easiest way to install Cartopy is by using
`Conda <https://conda.io/miniconda.html>`_. If conda is already installed,
installation is as easy as::

    conda install -c conda-forge cartopy

Other pre-built binaries
------------------------

Additional pre-built binaries can be found at a variety of sources, including:

* Christoph Gohlke (https://www.lfd.uci.edu/~gohlke/pythonlibs/)
  maintains unofficial Windows binaries of cartopy.
* `OSGeo Live <https://live.osgeo.org>`_.

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

Before building Cartopy from source, you need to **first** install the
required dependencies listed below. Once these are installed, Cartopy can be
installed using the pip installer::

    pip install cartopy

To instead install the most recent version found on the GitHub main branch,
use::

    pip install git+https://github.com/SciTools/cartopy.git

Alternatively, you can clone the git repo on your computer and install manually
using the `setup.py` file::

    git clone https://github.com/SciTools/cartopy.git
    cd cartopy
    # Uncomment the following to specify non-standard include and library paths
    # python setup.py build_ext -I/path/to/include -L/path/to/lib
    python setup.py install

Required dependencies
~~~~~~~~~~~~~~~~~~~~~

In order to install Cartopy, or to access its basic functionality, it will be
necessary to first install **GEOS**, **Shapely**, and
**pyshp**. Many of these packages can be installed using pip or
other package managers such as apt-get (Linux) and brew (macOS). Many of these
dependencies are built as part of Cartopy's conda distribution, and the recipes
for these packages can be found at https://github.com/conda-forge/feedstocks.

We include a conda environment file that contains a list of all the
dependencies required to build and install cartopy, which can be used to
install pre-built binaries of all the dependencies on your local system.
To use it::

    git clone https://github.com/SciTools/cartopy.git
    cd cartopy
    conda env create -f environment.yml
    conda activate cartopy-dev
    pip install -e .

You can also use your system's package manager to install the dependencies.

Ubuntu / Debian
_______________

On Debian, you can install the required system libraries using the system package manager::

    sudo apt -y install libproj-dev libgeos-dev

Then you can proceed to install cartopy using a python package manager::

    pip3 install cartopy

MacOS
_____

For macOS, the required dependencies can be installed in the following way::

    brew install proj geos
    pip3 install --upgrade pyshp
    # shapely needs to be built from source to link to geos. If it is already
    # installed, uninstall it by: pip3 uninstall shapely
    pip3 install shapely --no-binary shapely

Still on macOS, make sure you have installed pkg-config and set the
`PKG_CONFIG_PATH` environment variable as follows::

    brew install pkg-config
    export PKG_CONFIG_PATH=/usr/local/bin/pkgconfig

Then you can install cartopy using::

    pip3 install cartopy

Other
_____

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

Further information about the required dependencies can be found here:

**Python** 3.7 or later (https://www.python.org/)
    Python 2 support was removed in v0.19.

**Matplotlib** 3.1 or later (https://matplotlib.org/)
    Python package for 2D plotting. Python package required for any
    graphical capabilities.

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

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

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

**PROJ** 8.0.0 or later (https://proj.org/)
    Coordinate transformation library.

**pyproj** 3.0.0 or later (https://github.com/pyproj4/pyproj/)
    Python interface to PROJ (cartographic projections and coordinate transformations library).

Optional Dependencies
~~~~~~~~~~~~~~~~~~~~~

To make the most of Cartopy by enabling additional functionality, you may want
to install these optional dependencies.

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

**Pillow** 6.1.0 or later (https://python-pillow.org)
    A popular fork of PythonImagingLibrary.

**pykdtree** 1.2.2 or later (https://github.com/storpipfugl/pykdtree)
    A fast kd-tree implementation that is used for faster warping
    of images than SciPy.

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

**OWSLib** 0.18 (https://pypi.python.org/pypi/OWSLib)
     A Python package for client programming with the Open Geospatial
     Consortium (OGC) web service, and which gives access to Cartopy ogc
     clients.

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

Testing Dependencies
~~~~~~~~~~~~~~~~~~~~

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

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

**pytest-mpl** 0.11 or later (https://github.com/matplotlib/pytest-mpl)
    Pytest plugin to faciliate image comparison for Matplotlib figures

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