This section contains some frequently asked questions (FAQs) regarding Ginga usage.


Does Ginga run on Mac/Windows/Linux/XYZ?

Ginga is written entirely in the Python programming language, and uses only supporting Python packages. As long as a platform supports Python and the necessary packages, it can run some version of Ginga. On recent Linux, Mac and Windows versions, all of these packages are available.

Does Ginga work with Python 3?

Yes, but only Python 3.7 or later. Just install with Python 3. Of course, you need all the supporting modules for Python 3 (NumPy, SciPy, Qt 5, etc.).

Does Ginga work with Python 2?

No. If you absolutely have to use Python 2, please downgrade to Ginga 2.x series.


What GUI toolkit does Ginga use?

It depends what exactly you want to run. Ginga is both a toolkit for building viewers and also includes a “reference viewer”. The example programs currently support Qt, GTK, Tk, matplotlib and web browser via HTML5 canvas. Some other toolkits are being worked on and may be partially supported.

The full reference viewer currently supports Qt (PyQt5, PyQt6, PySide2, PySide6) and Gtk (ver 3). The difference is explained here, in Section Developing with Ginga.

Control Bindings

Can I get DS9-like user interface mappings?

Save the file called bindings.cfg.ds9 and drop it in your $HOME/.ginga folder as “bindings.cfg”. Then restart Ginga.

Can I customize the user interface mappings?

Yes. There is more information in the Binding Config File section.

Where can I find a quick reference of the bindings?

See Section Quick Reference.


Does Ginga work with SAMP?

Yes. See Section SAMP Control.

Is it possible to control Ginga remotely?

Yes. See Section RC.

When are you going to add the XYZ feature that DS9 has?

Maybe never. The Ginga package design goal was never to replace DS9, but to provide a full featured Python FITS widget that we could use to build directly in Python. This is clearly seen if you look at the example programs in examples/*/example*.py. The idea was to make it easy for someone to build any kind of custom viewer by having a full-featured widget to build on.

That said, we did write a reference viewer because we needed something with many of the convenience features of a modern FITS viewer. DS9 is almost the size of a small OS, however, and I’m not sure it is wise to try to match it feature for feature. Instead, since Ginga is plugin-based, you can write plugins to give you the features you need. DS9 is a “everything including kitchen sink” kind of viewer, whereas ginga reference viewer is more like a “take what you need from the pantry and whip it up” type viewer.

Please send a pull request!

Can I get Ginga reference viewer to save its size and position?

Yes. Add the line "save_layout = True" to your ~/.ginga/general.cfg file.

If the file does not exist, create it, or copy the one from ginga/examples/configs/general.cfg.

World Coordinate System

What library are you using for WCS?

We are lucky to have several possible choices for a Python WCS package compatible with Ginga: AstLib, Kapteyn, Starlink, and Astropy WCS.

Kapteyn and Astropy wrap Mark Calabretta’s “WCSLIB”, AstLib wraps Jessica Mink’s “wcstools”, and I’m not sure what Starlink uses. Note that AstLib and Starlink require Astropy to be installed in order to create a WCS object from a FITS header.

To force the use of a particular one add this to your “general.cfg” in $HOME/.ginga:

WCSpkg = 'package'

Replace 'package' with one of 'Astropy', 'Kapteyn', 'Starlink', 'astlib', or 'choose'. If you pick 'choose', Ginga will try to pick one for you.

How easy is it for Ginga to support a custom WCS?

Pretty easy. See Section I want to use my own World Coordinate System!.

I/O and File Formats

What library are you using for FITS I/O?

There are two possible choices for a Python FITS file reading package compatible with Ginga: Astropy FITS and fitsio. Both are originally based on the CFITSIO library (although Astropy’s version uses very little of it any more, while fitsio is still tracking the current version).

To force the use of a particular one add this to your “general.cfg” in $HOME/.ginga:

FITSpkg = ‘package’

Replace 'package' with one of 'Astropy', 'fitsio', or 'choose'. If you pick 'choose', Ginga will try to pick one for you.

How easy is it for Ginga to support a new file formats besides FITS?

Pretty easy. See Section I want to use my own file storage format, not FITS!.

Problems Displaying Images

Nothing changes in the image when I change settings under “Preferences”.


The Preferences plugin sets the preferences on a per-channel basis. Make sure the channel you are looking at has the same name as the prefix for the preferences. For example: “Image” and “Image: Preferences” or “Image1” and “Image1: Preferences”.

The preferences for a given channel are copied from the default “Image” channel until they are explicitly set and saved using this plugin. So if you want preferences that follow around from channel to channel, save them as preferences for “Image” and any new channels created will get those as well, unless you have saved different ones under those channel names.

Nothing changes in the image when I change the “Auto Cuts” settings under Preferences. I’ve checked that I’m adjusting preferences for the same channel that I’m viewing.


What is the setting for “Cut New” under the New Images section in Preferences for this channel?

If that setting is “Off” then you have elected not to have Ginga apply Auto Levels when an image is loaded in that channel. Press ‘a’ in the image window to force an auto cut levels and it will use the new settings.

No image shows in the display, and I get an error in the terminal about histogram and keyword “density”.


You need a newer version of NumPy.

I recommend getting NumPy v1.14 or later.