Getting started

Getting Access to GBDX

All operations on GBDX require credentials. You can sign up for a GBDX account at Your GBDX credentials are found under your account profile.

Gbdxtools expects a config file to exist at ~/.gbdx-config with your credentials. Instead of a file your credentials can also be stored as the environmental variables GBDX_USERNAME and GBDX_PASSWORD. For more information on the credential file and other ways to manage authorization, see

Gbdxtools automatically handles authentication and authorization. It is not required to manually log in or start a session.

For questions or troubleshooting email

Using Gbdxtools

Local Python Environment

As an access library to GBDX APIs, gbdxtools can be run locally. See Installation below.

Jupyter Notebooks

Gbdxtools has additional features for visualization and mapping in IPython and Jupyter Notebooks. This is the recommended development environment for analysis.

GBDX Notebooks

DigitalGlobe also offers GBDX Notebooks, a hosted instance of Jupyter Notebooks that provides a ready-to-go development environment. The platform also features sharing of notebooks, map-based image searching, and other features. For more information, see


Conda is the recommended way to install gbdxtools:

conda install -c conda-forge -c digitalglobe gbdxtools

Pip can also be used:

pip install gbdxtools


These are various tips to follow if your installation fails.


As of gbdxtools version 0.11.3 libcurl and GDAL (>=2.1.0) are required. To install these packages use:

# Ubuntu users:
sudo add-apt-repository -y ppa:ubuntugis/ubuntugis-unstable
sudo apt update
sudo apt-get install gdal-bin python-gdal python3-gdal libcurl4-openssl-dev

# Mac Users:
xcode-select --install # to install libcurl
brew install

Windows Users

Conda installation should work fine on windows for python version 2.7. If you are using python 3, you can install with pip, first install some dependencies with conda:

conda install -c conda-forge scipy
conda install -c conda-forge scikit-image
pip install gbdxtools


Make sure you have the latest pip version:

pip install pip --upgrade

Ubuntu users

If you run into trouble with the installation of cryptography, make sure that the following dependencies are installed:

sudo apt-get install build-essential libssl-dev libffi-dev python-dev libcurl4-openssl-dev

Mac OSX Users

If you run into trouble with the installation of cryptography and see a message that <ffi.h> could not be found, you can run:

xcode-select --install

Then run “pip install gbdxtools” again. See stackoverflow for discussion on what is going wrong and why this fixes it (

If you are running in a virtualenv and run into issues you may need upgrade pip in the virtualenv:

cd <your_project_folder>
. venv/bin/activate
pip install --upgrade pip
pip install --upgrade gbdxtools
# you might also need to remove token from your .gbdx-config file
nano -w ~.gbdx-config
# then, remove the [gbdx_token] section and json= part

Users installing gbdxtools on OS X Mojave have encountered:

__main__.ConfigurationError: Curl is configured to use SSL, but we have not been able to determine which SSL backend it is using. Please see PycURL documentation for how to specify the SSL backend manually.

This solution was reported to work:

brew install openssl
PYCURL_SSL_LIBRARY=openssl LDFLAGS="-L/usr/local/opt/openssl/lib" CPPFLAGS="-I/usr/local/opt/openssl/include" pip install --no-cache-dir pycurl
pip install gbdxtools

This assumes you are installing in a fresh environment. If pycurl or gbdxtools are already installed they should be uninstalled first.


Versions of gbdxtools >= 0.11.3 require the GDAL library (>= 2.1.0) to be installed.


If your installation with pip keeps failing, try creating a conda environment and installing gbdxtools within this environment.

For Ubuntu, install conda with the following commands (choose default options at prompt):


For OS X, install conda with the following commands (choose default options at prompt):


Make sure that conda is in your path. Then create a conda environment:

conda create -n env python ipython

Activate the environment:

source activate env

Upgrade pip (if required):

pip install pip --upgrade

Install gbdxtools:

conda install -c digitalglobe  gbdxtools

Python versions and conda-forge

A known issue exists, in certain environments, where conda will downgrade python from 3.x to 2.7x when installing gbdxtools. If conda does not keep your python version intact when installing gbdxtools, you need to:

conda install -y gbdxtools -c digitalglobe -c conda-forge