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 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 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.8 or later (https://www.python.org/)
    Python 2 support was removed in v0.19.

**Matplotlib** 3.2 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.

**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.