Skip to content
The modular galaxy image simulation toolkit. Documentation:
Python C++ TeX Jupyter Notebook sed C Other
Branch: releases/2.2
Clone or download

Latest commit

Latest commit a633a3e May 14, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
bin 2019 Aug 20, 2019
devel typo Nov 26, 2019
docs Update docs May 14, 2020
examples grammar Sep 2, 2019
galsim v2.2.4 May 14, 2020
include A couple more assert -> xassert and avoid using assert.h May 14, 2020
lib Put .gitignore files in bin and lib to make sure those directories ar… Feb 24, 2012
share Add option to use GALSIM_SHARE_DIR environment variable to set share_dir Aug 27, 2019
src A couple more assert -> xassert and avoid using assert.h May 14, 2020
tests Fix test for a change in meds repo behavior May 14, 2020
ups Use lsst's galsim.table Aug 27, 2019
.codecov.yml add codecov token to .codecov.yml Aug 21, 2019
.gitattributes Treat fits files as binary Dec 31, 2013
.travis.yml Allow all but main 4 to fail Sep 9, 2019
CHANGELOG.rst Update CHANGELOG May 14, 2020
Doxyfile Update version to 2.1 Nov 22, 2018
INSTALL.rst Reorg installation instructions Aug 20, 2019
LICENSE 2019 Aug 20, 2019 Don't need include_package_data anymore and using with symlink messes… Sep 2, 2019
README.rst Make Rachel's suggested changes Aug 20, 2019
clean_docs Add clean_docs script to make it easier to clean up the docs/_build d… Aug 21, 2019
conda_requirements.txt Add setuptools>=38 as a build_dep. Feb 19, 2018
pyproject.toml Fix for pip 10.x when eigncy is required Jul 19, 2018
requirements.txt Don't use pyast 3.13 Nov 26, 2019 Fix travis.yml syntax error Sep 7, 2019
test_requirements.txt Don't guard against ImportError for yaml in tests that use it. May 24, 2018
update_docs First pass at the Sphinx pages: just Image and GSObject so far Aug 20, 2019


GalSim is open-source software for simulating images of astronomical objects (stars, galaxies) in a variety of ways. The bulk of the calculations are carried out in C++, and the user interface is in python. In addition, the code can operate directly on "config" files, for those users who prefer not to work in python. The impetus for the software package was a weak lensing community data challenge, called GREAT3:

However, the code has numerous additional capabilities beyond those needed for the challenge, and has been useful for a number of projects that needed to simulate high-fidelity galaxy images with accurate sizes and shears. At the end of this file, there is a list of the code capabilities and plans for future development. For details of algorithms and code validation, please see

Basic Installation

Normally, to install GalSim, you should just need to run:

pip install galsim

Depending on your setup, you may need to add either sudo to the start or --user to the end of this command as you normally do when pip installing packages.

See Installation Instructions for full details including one dependency (FFTW) that is not pip installable, so you may need to install before running this command.

You can also use conda via conda-forge:

conda install -c conda-forge galsim

Source Distribution

To get the latest version of the code, you can grab the tarball (or zip file) from

Also, feel free to fork the repository:

Or clone the repository with either of the following:

git clone
git clone

The code is also distributed via Fink, Macports, and Homebrew for Mac users. See Installation Instructions (in INSTALL.rst) for more information.

The code is licensed under a BSD-style license. See the file LICENSE for more details.

Keeping up-to-date with GalSim

There is a GalSim mailing list, organized through the Google Group galsim-announce. Members of the group will receive news and updates about the GalSim code, including notifications of major version releases, new features and bugfixes.

You do not need a Google Account to subscribe to the group, simply send any email to:

If you receive a confirmation request (check junk mail filters!) simply reply directly to that email, with anything, to confirm. You may also click the link in the confirmation request, but you may be asked for a Google Account login.

To unsubscribe, simply send any email to:

You should receive notification that your unsubscription was successful.

How to communicate with the GalSim developers

Currently, the lead developers for GalSim are:

  • Mike Jarvis (mikejarvis17 at gmail)
  • Rachel Mandelbaum (rmandelb at andrew dot cmu dot edu)
  • Josh Meyers (jmeyers314 at gmail)

However, many others have contributed to GalSim over the years as well, for which we are very grateful.

If you have a question about how to use GalSim, a good place to ask it is at StackOverflow. Some of the GalSim developers have alerts set up to be automatically notified about questions with the 'galsim' tag, so there is a good chance that your question will be answered.

If you have any trouble installing or using the code, or find a bug, or have a suggestion for a new feature, please open up an Issue on our GitHub repository. We also accept pull requests if you have something you'd like to contribute to the code base.

If none of these communication avenues seem appropriate, you can also contact us directly at the above email addresses.

Demonstration scripts

There are a number of scripts in examples/ that demonstrate how the code can be used. These are called ... You can run them by typing (e.g.) python while sitting in examples/, All demo scripts are designed to be run in the examples/ directory. Some of them access files in subdirectories of the examples/ directory, so they would not work correctly from other locations.

A completely parallel sequence of configuration files, called demo1.yaml ... demo11.yaml, demonstrates how to make the same set of simulations using config files that are parsed by the executable bin/galsim. (There are no corresponding .yaml files for demo12 and demo13 yet, because some of the functionality cannot yet be carried out using config files.)

Two other scripts in the examples/ directory that may be of interest, but are not part of the GalSim tutorial series, are, which demonstrates the use of the FourierSqrt transformation to optimally coadd images, and, which demonstrates the realistic atmospheric PSF code by making a movie of a time-variable PSF and wavefront.

As the project develops through further versions, and adds further capabilities to the software, more demo scripts may be added to examples/ to illustrate what GalSim can do.

Summary of current capabilities

Currently, GalSim has the following capabilities:

  • Can generate PSFs from a variety of simple parametric models such as Moffat, Kolmogorov, and Airy, as well as an optical PSF model that includes Zernike aberrations to arbitrary order, and an optional central obscuration and struts.

  • Can simulate galaxies from a variety of simple parametric models as well as from real HST data. For information about downloading a suite of COSMOS images, see

  • Can simulate atmospheric PSFs from realistic turbulent phase screens.

  • Can make the images either via i) Fourier transform, ii) real-space convolution (real-space being occasionally faster than Fourier), or iii) photon-shooting. The exception is that objects that include a deconvolution (such as RealGalaxy objects) must be carried out using Fourier methods only.

  • Can handle wavelength-dependent profiles and integrate over filter bandpasses appropriately.

  • Can apply shear, magnification, dilation, or rotation to a galaxy profile including lensing-based models from a power spectrum or NFW halo profile.

  • Can draw galaxy images into arbitrary locations within a larger image.

  • Can add noise using a variety of noise models, including correlated noise.

  • Can whiten or apply N-fold symmetry to existing correlated noise that is already in an image.

  • Can read in input values from a catalog, a dictionary file (such as a JSON or YAML file), or a fits header.

  • Can write images in a variety of formats: regular FITS files, FITS data cubes, or multi-extension FITS files. It can also compress the output files using various compressions including gzip, bzip2, and rice.

  • Can carry out nearly any simulation that a user might want using two parallel methods: directly using python code, or by specifying the simulation properties in an input configuration script. See the demo scripts in the examples/ directory for examples of each.

  • Supports a variety of possible WCS options from a simple pixel scale factor of arcsec/pixel to affine transforms to arbitrary functions of (x,y), including a variety of common FITS WCS specifications.

  • Can include a range of simple detector effects such as nonlinearity, brighter-fatter effect, etc.

  • Has a module that is particularly meant to simulate images for the WFIRST survey.

Planned future development

We plan to add the following additional capabilities in future versions of GalSim:

  • Wavelength-dependent photon shooting. Currently, the chromatic functionality is only available for FFT rendering, which is quite slow. For most use cases, photon shooting should be orders of magnitude faster, so this is a near-term priority to get done. (cf. Issue #540)
  • Simulating more sophisticated detector defects and image artifacts. E.g. vignetting, fringing, cosmic rays, saturation, bleeding, ... (cf. Issues #553, #828)
  • Proper modeling of extinction due to dust. (cf. Issues #541, #550)
  • Various speed improvements. (cf. Issues #205, #566, #875, #935)

There are many others as well. Please see

for a list of the current open issues. And feel free to add an issue if there is something useful that you think should be possible, but is not currently implemented.

You can’t perform that action at this time.