Skip to the navigation links
Last modified: 6 April 2020


Conda Installation

1. Introduction

CIAO 4.12 can now be installed using conda. This installation method is experimental.

conda is a package management and environment management system. It is similar to other package managers (such as yum, apt, macports, dnf) but allows for users to create multiple environments with multiple versions of packages which can co-exist on the same system. Users can easily install pre-compiled and pre-configured packages from curated channels (repositories) into various environments. Users then activate the environment to run the applications.

Feedback Requested

The CXC is actively requesting feedback on the conda edition of CIAO-4.12. We would like to hear from users: successes and problems. Users can send comments to the CXC Helpdesk.

With conda , Linux and Mac users can choose to install CIAO-4.12 using either Python 3.7, 3.6, or 3.5. Using the conda package manager users can also install additional third-party packages.

2. Install conda

Users must already have conda installed on their systems. This can be either Anaconda or miniconda. CIAO-4.12 is available for Linux and MacOSX, not Windows.

Minimum conda version?

Some users, macOSX in particular, have reported problems with using old versions of conda. CIAO has successfully be installed using conda 4.7.6 and newer. Users should consider upgrading their base conda installation before installing CIAO.

Users can check if they have conda and the version using

$ conda --version
conda: Command not found.

In this case, conda is not installed or otherwise not setup in the user's PATH.

Help installing conda

Users should consult the Anaconda troubleshooting guide if they encounter problems installing conda instead of the CXC helpdesk. Timeout's during download are frequent. Users are encouraged to simply try again.

Below are the basic instructions for installing miniconda.

Linux$ curl -o 


macOS$ curl -o

Users can then run the interactive installation script

$ bash 

... accept license and answer prompts ... 

Preparing transaction: done
Executing transaction: done
installation finished.
Do you wish the installer to initialize Miniconda3
by running conda init? [yes|no]
[no] >>> 
tcsh shell users

Users who use the tcsh shell must not run the conda init command suggested by the conda installer. It has a serious bug that may prevent users from running commands or may even prevent users from logging into their user account.

This does not affect users using the bash shell. If unsure which you are using check the output from

$ echo $0

After the installer has finished users will want to be sure that the conda command is setup in their PATH environment.

bash$ PATH="${PATH}:<<directory where miniconda was installed>>/bin"


tcsh% set path = ( ${path} <<directory where miniconda was installed>>/bin )

3. Create a new CIAO environment

The CXC is hosting the CIAO-4.12 packages on our own conda channel. This is due to the size of the packages.

To create a new conda environment with CIAO installed users run the following command:

$ conda create -n ciao-4.12 \
  -c \
  ciao sherpa ds9 ciao-contrib caldb_main marx

This will create an environment named ciao-4.12 and perform a standard CIAO installation including the standard CALDB. Users who need the ACIS or HRC background event files should replace caldb_main with simply caldb.

Users can choose to install CIAO with either Python 3.7 (default), 3.6, or 3.5. Use the following example to select a different python version:

$ conda create -n ciao-4.12_python35 \
  -c \
  python=3.5 ciao sherpa ds9 ciao-contrib caldb_main marx

Timeouts during download are frequent. Users are encouraged to simply try again.

Blank sky background CALDB files

To install the ACIS and HRC blank sky background files users should replace caldb_main with caldb.

$ conda create -n ciao-4.12 \
  -c \
  ciao sherpa ds9 ciao-contrib caldb marx

Alternative: use conda env instead

The conda create example above allows conda to resolve all the package dependencies and will select the latest compatible versions of those packages. There may be circumstances where this causes problems. As an alternative, user can install CIAO using exactly the same version of all the packages that were available when CIAO was released using the conda env command:

$ conda env create -n ciao-4.12 cxc/ciao-4.12-caldb-<platform>
$ conda env create -n ciao-4.12 cxc/ciao-4.12-<platform>

where <platform> is either linux or macos. The -caldb environment installs the caldb_main package. Users can then later include the blank sky background files by

$ conda install -n ciao-4.12 -c \
  acis_bkg_evt hrc_bkg_evt

As with any conda package, this command can be used to install the blank sky background files in any environment at any time.

4. Activate CIAO environment

Once the CIAO environment is created, it has to be activated. This is equivalent to source'ing the CIAO setup scripts.

For bash shell users, make sure conda's activate script is in your PATH and then simply

$ source activate ciao-4.12

where ciao-4.12 is the name of the environment you just created.

For tcsh shell users

% alias conda source <<directory where miniconda was installed>>/etc/profile.d/conda.csh
% conda activate ciao-4.12

Users may wish to add the alias to their $HOME/.tcshrc startup files.

By default, users will notice the shell prompt has changed to indicate the current conda environment.

$ source activate ciao-4.12
(ciao-4.12) $

5. Run smoke tests

Users are encouraged to run the CIAO smoke tests to ensure everything is installed and working correctly.

(ciao-4.12)$ cd $ASCDS_INSTALL/test
(ciao-4.12)$ make

If users choose to omit packages (eg sherpa or ds9), then smoke tests associated with those packages will fail.

6. Install additional packages

Additional packages can then be installed into the CIAO environment using the conda installer.

(ciao-4.12)$ conda install -n ciao-4.12 jupyter

Due to the constraints on python version and numpy version, users may not be able to install certain packages, or possibly the latest versions of certain packages such as astropy or scipy. Similarly, users may not be able to install CIAO into an existing environment with incompatible versions of python or numpy.

7. Leave CIAO environment

Use the deactivate command to leave the conda environment:

(ciao-4.12)$ conda deactivate

8. Update CIAO environment

Users can install the latest CIAO and CALDB updates using the conda update command

$ conda update -n ciao-4.12 \
  -c \
  ciao sherpa ds9 ciao-contrib caldb_main marx

Only the packages listed will be updated. To update all the packages in the environment use the --all option.

After updating, users may want to run the conda clean command to completely remove the previous versions. This is especially true when updating the CALDB since each CALDB update is a full release which each requires 5-12Gb of disk space.

$ conda clean --all

Known Problems

Users should be aware of these known issues before using the conda ciao installation.

  1. The conda installation will seem to hang during the installation process when retrieving the largest segments: the XSPEC models and CALDB files. Do not kill the installation. If it times out then it will be able resume and only install the failed packages.

  2. Users who keep the CALDB separate from the CIAO installation must setup the following environment variables independently from the conda setup.

    $ export CALDB=/Some/Other/Directory/CALDB
    $ export CALDBCONFIG=${CALDB}/software/tools/caldb.config
    $ export CALDBALIAS=${CALDB}/software/tools/alias_config.fits

    These can be setup in the users' login script ($HOME/.bash_profile), or setup each time the environment is activated. They can be setup either before or after the conda environment is activated.

    The CALDB version will not be reported by the ciaover command if it is not installed by conda

  3. Due to the constraints on python version and numpy version, users may not be able to install CIAO in the same environment as existing packages. Known incompatibilities include:

    • CIAO and StSCI's astroconda which fail due to version incompatibilities in the CFITSIO library.
    • There is a conflict between CIAO and HEASARC's XSPEC package. Users must
      1. First, initialize their HEASARC environment

        $ export HEADAS=/soft/lheasoft/headas/x86_64-pc-linux 
        $ source $HEADAS/
      2. Then activate their CIAO environment

        $ conda activate ciao-4.12
      3. Finally, users have to restore the HEADAS environment variable back to it's original value

        $ export HEADAS=/soft/lheasoft/headas/x86_64-pc-linux 

      Note: this may cause problems using XSpec models in sherpa. Users must not source the script after activating the CIAO environment as it will cause incompatibilities in the suite of parameters tools: pset, pget, and plist.

  4. Users must not activate CIAO conda environment in the same terminal (shell) where the classic CIAO setup script (eg ciao.bash) has already been sourced. Similarly, users must not source the CIAO setup scripts in an activate CIAO conda environment. The results in both cases are corrupted environments which can lead to unexpected failures.