Getting started


EarthSim supports Python 3.6 on Linux, Windows, or Mac.

EarthSim itself is a pure Python package that itself would be easy to install, but it depends on several packages (gdal, geos, and others) that are linked against binary-code geospatial libraries. Unfortunately, incompatibly compiled versions of those libraries are available from different sources, which can make it difficult to assemble an appropriate environment for safely running EarthSim. For this reason, EarthSim is currently provided via a special set of installation steps based on conda and git that ensure only a compatible set of packages is used. Specifically:

1. Install Python 3 Miniconda or Anaconda , if you don’t already have it on your system.

  1. Clone the EarthSim git repository if you do not already have it:

    git clone git://
  2. Set up an environment with all of the dependencies needed to run the examples:

    cd EarthSim
    conda create -n earthsim -c conda-forge --file=dependencies.txt conda-forge::python=3.6
  3. Activate the earthsim environment:

    activate earthsim

    for Windows; MacOS and Linux users should instead run:

    source activate earthsim
  4. Install the earthsim module into this environment:

    pip install -e .
  5. Download the sample files:

    earthsim examples

These instructions are designed to build a working environment repeatably on Mac OS X, Windows, and Linux platforms, pinning dependencies to known versions to avoid incompatibilities with new releases of the software required.


Once you’ve installed EarthSim as above and are in the EarthSim directory, you can run the examples shown on the website using Jupyter :

cd earthsim-examples
jupyter notebook

You should now be able to select one of the user-guide or topics notebooks and run it in Jupyter.

Exploring Further

You can look through the User Guide and the Topics to see examples, but most of the documentation is at the sites for the packages like HoloViews that are used in the examples. A good way to get comfortable with those tools is to work through the tutorials at

If you find any bugs or have any feature suggestions please file a GitHub issue or submit a pull request .


Assuming you are in the EarthSim directory, and the earthsim conda environment is active, you can update to the latest version of EarthSim as follows:

  1. Get updated code and examples from git:

    git pull
  2. Update the earthsim conda environment:

    conda install -c pyviz/label/earthsim -c conda-forge --file=dependencies.txt
  3. Get a new copy of the examples to work on, and download new or updated data:

    earthsim examples


If you are actively collaborating with the EarthSim developers and want to try out the latest pyviz work as it first appears (which is not necessarily functional or stable), you can run the following after creating or updating (and activating) your earthsim environment:

conda install -c pyviz/label/dev -c conda-forge --file=dependencies-dev-overrides.txt

This command will update the main packages to the latest dev releases, which appear periodically after new features are added.

If you really want to be on the bleeding edge, you can instead get the absolute latest changes by cloning the earthsim, holoviews, geoviews, datashader, param, and panel Github repositories and running pip install -e . inside each one, pulling new changes from each of these libraries as needed. That’s what the main developers do, but it isn’t recommended for other users unless you are very skilled at debugging the broken environments that are likely to appear as packages change unpredictably over time.