There are two ways to install dustmaps.

1. Using pip

From the commandline, run

pip install dustmaps

You may have to use sudo.

Next, we’ll configure the package and download the dust maps we’ll want to use. Start up a python interpreter and type:

from dustmaps.config import config
config['data_dir'] = '/path/to/store/maps/in'

import dustmaps.sfd

import dustmaps.planck

import dustmaps.planck

import dustmaps.bayestar

import dustmaps.iphas

import dustmaps.marshall

import dustmaps.chen2014

import dustmaps.lenz2017

import dustmaps.pg2010

import dustmaps.leike_ensslin_2019

import dustmaps.leike2020

All the dust maps should now be in the path you gave to config['data_dir']. Note that these dust maps can be very large - some are several Gigabytes! Only download those you think you’ll need.

Note that there are two versions of the Bayestar dust map. By default, dustmaps.bayestar.fetch() will download Bayestar19 (Green et al. 2019). In order to download earlier version of the map (Green et al. 2015, 2018), you can provide the keyword argument version='bayestar2017' (Green et al. 2018) or version='bayestar2015' (Green et al. 2015).

2. Using

An alternative way to download dustmaps, if you don’t want to use pip, is to download or clone the respository from

In this case, you will have to manually make sure that the dependencies are satisfied:

  • numpy
  • scipy
  • astropy
  • h5py
  • healpy
  • requests
  • six
  • progressbar2

These packages can typically be installed using the Python package manager, pip.

Once these dependencies are installed, run the following command from the root directory of the dustmaps package:

python install --large-data-dir=/path/to/store/maps/in

Then, fetch the maps you’d like to use. Depending on which dust maps you choose to download, this step can take up several Gigabytes of disk space. Be careful to only download those you think you’ll need:

python fetch --map-name=sfd
python fetch --map-name=planck
python fetch --map-name=planckGNILC
python fetch --map-name=bayestar
python fetch --map-name=iphas
python fetch --map-name=marshall
python fetch --map-name=chen2014
python fetch --map-name=lenz2017
python fetch --map-name=leikeensslin2019
python fetch --map-name=leike2020

That’s it!

Note that the above code will download the latest version of the Bayestar dust map (the 2019 version). If you want to download the 2015 and 2017 versions, you can enter the commands

python fetch --map-name=bayestar2015
python fetch --map-name=bayestar2017

3. Custom configuration file location (Optional)

By default, a configuration file is stored in ~/.dustmapsrc. This file might look like the following:

{"data_dir": "/path/to/store/maps/in"}

If you would like dustmaps to use a different configuration file, then you can set the environmental variable DUSTMAPS_CONFIG_FNAME. For example, in a bash terminal,

export DUSTMAPS_CONFIG_FNAME=/path/to/custom/config/file.json

The paths listed in the configuration file can also include environmental variables, which will be expanded when dustmaps is loaded. For example, the configuration file could contain the following:

{"data_dir": "/path/with/${VARIABLE}/included"}

If the environmental variable VARIABLE is set to "foo", for example, then dustmaps will expand data_dir to "/path/with/foo/included".