Executable Scripts

PyFITS installs a couple of useful utility programs on your system that are built with PyFITS.


fitsinfo is a command-line script based on PyFITS for printing a summary of the HDUs in one or more FITS files(s) to the standard output.

Example usage of fitsinfo:

  1. Print a summary of the HDUs in a FITS file:

    $ fitsinfo filename.fits
    Filename: filename.fits
    No.    Name         Type      Cards   Dimensions   Format
    0    PRIMARY     PrimaryHDU     138   ()
    1    SCI         ImageHDU        61   (800, 800)   int16
    2    SCI         ImageHDU        61   (800, 800)   int16
    3    SCI         ImageHDU        61   (800, 800)   int16
    4    SCI         ImageHDU        61   (800, 800)   int16
  2. Print a summary of HDUs of all the FITS files in the current directory:

    $ fitsinfo *.fits


fitsheader is a command line script based on pyfits for printing the header(s) of one or more FITS file(s) to the standard output in a human- readable format.

Example uses of fitsheader:

  1. Print the header of all the HDUs of a .fits file:

    $ fitsheader filename.fits
  2. Print the header of the third and fifth HDU extension:

    $ fitsheader --extension 3 --extension 5 filename.fits
  3. Print the header of a named extension, e.g. select the HDU containing keywords EXTNAME=’SCI’ and EXTVER=‘2’:

    $ fitsheader --extension "SCI,2" filename.fits
  4. Print only specific keywords:

    $ fitsheader --keyword BITPIX --keyword NAXIS filename.fits
  5. Print keywords NAXIS, NAXIS1, NAXIS2, etc using a wildcard:

    $ fitsheader --keyword NAXIS* filename.fits

Note that compressed images (HDUs of type CompImageHDU) really have two headers: a real BINTABLE header to describe the compressed data, and a fake IMAGE header representing the image that was compressed. PyFITS returns the latter by default. You must supply the --compressed option if you require the real header that describes the compression.

With PyFITS installed, please run fitsheader --help to see the full usage documentation.


fitscheck is a command line script based on pyfits for verifying and updating the CHECKSUM and DATASUM keywords of .fits files. fitscheck can also detect and often fix other FITS standards violations. fitscheck facilitates re-writing the non-standard checksums originally generated by pyfits with standard checksums which will interoperate with CFITSIO.

fitscheck will refuse to write new checksums if the checksum keywords are missing or their values are bad. Use --force to write new checksums regardless of whether or not they currently exist or pass. Use --ignore-missing to tolerate missing checksum keywords without comment.

Example uses of fitscheck:

  1. Verify and update checksums, tolerating non-standard checksums, updating to standard checksum:

    $ fitscheck --checksum either --write *.fits
  2. Write new checksums, even if existing checksums are bad or missing:

    $ fitscheck --write --force *.fits
  3. Verify standard checksums and FITS compliance without changing the files:

    $ fitscheck --compliance *.fits
  4. Verify original nonstandard checksums only:

    $ fitscheck --checksum nonstandard *.fits
  5. Only check and fix compliance problems, ignoring checksums:

    $ fitscheck --checksum none --compliance --write *.fits
  6. Verify standard interoperable checksums:

    $ fitscheck *.fits
  7. Delete checksum keywords:

    $ fitscheck --checksum none --write *.fits
Usage: fitscheck [options] <.fits files...>

        .e.g. fitscheck example.fits

        Verifies and optionally re-writes the CHECKSUM and DATASUM keywords
        for a .fits file.
        Optionally detects and fixes FITS standard compliance problems.

  -h, --help            show this help message and exit
  -k [standard | nonstandard | either | none], --checksum=[standard | nonstandard | either | none]
                        Choose FITS checksum mode or none.  Defaults standard.
  -w, --write           Write out file checksums and/or FITS compliance fixes.
  -f, --force           Do file update even if original checksum was bad.
  -c, --compliance      Do FITS compliance checking; fix if possible.
  -i, --ignore-missing  Ignore missing checksums.
  -v, --verbose         Generate extra output.


fitsdiff provides a thin command-line wrapper around the FITSDiff interface–it outputs the report from a FITSDiff of two FITS files, and like common diff-like commands returns a 0 status code if no differences were found, and 1 if differences were found:

  Compare two FITS image files and report the differences in header keywords and

    fitsdiff [options] filename1 filename2

where filename1 filename2 are the two files to be compared.  They may also be
wild cards, in such cases, they must be enclosed by double or single quotes, or
they may be directory names.  If both are directory names, all files in each of
the directories will be included; if only one is a directory name, then the
directory name will be prefixed to the file name(s) specified by the other
argument.  for example::

    fitsdiff "*.fits" "/machine/data1"

will compare all FITS files in the current directory to the corresponding files
in the directory /machine/data1.

--help, -h              show this help message and exit
--quiet, -q             Produce no output and just return a status code.
--num-diffs=INTEGER, -n INTEGER
                        Max number of data differences (image pixel or table
                        element) to report per extension (default 10).
--difference-tolerance=NUMBER, -d NUMBER
                        The relative tolerance for comparison of two numbers,
                        specifically two floating point numbers.  This applies
                        to data in both images and tables, and to floating
                        point keyword values in headers (default 0.0).
--no-ignore-blanks, -b  Don't ignore trailing blanks (whitespace) in string
                        values.  Otherwise trailing blanks both in header
                        keywords/values and in table column values) are not
                        treated as significant i.e., without this option
                        'ABCDEF   ' and 'ABCDEF' are considered equivalent.
                        Don't ignore entirely blank cards in headers.
                        Normally fitsdiff does not consider blank cards when
                        comparing headers, but this will ensure that even
                        blank cards match up.
--exact                 Report ALL differences, overriding command-line
                        options and FITSDIFF_SETTINGS.
--output-file=FILE, -o FILE
                        Output results to this file; otherwise results are
                        printed to stdout.

Header Comparison Options
--ignore-keywords=KEYWORDS, -k KEYWORDS
                        Comma-separated list of keywords not to be compared.
                        Keywords may contain wildcard patterns.  To exclude
                        all keywords, use "*"; make sure to have double or
                        single quotes around the asterisk on the command-line.
--ignore-comments=KEYWORDS, -c KEYWORDS
                        Comma-separated list of keywords whose comments will
                        not be compared.  Wildcards may be used as with

Table Comparison Options
--ignore-fields=COLUMNS, -f COLUMNS
                        Comma-separated list of fields (i.e. columns) not to
                        be compared.  All columns may be excluded using "*" as
                        with --ignore-keywords.

If the two files are identical within the specified conditions, it will report
"No difference is found." If the value(s) of -c and -k takes the form
'@filename', list is in the text file 'filename', and each line in that text
file contains one keyword.


    fitsdiff -k filename,filtnam1 -n 5 -d 1.e-6 test1.fits test2

This command will compare files test1.fits and test2.fits, report maximum of 5
different pixels values per extension, only report data values larger than
1.e-6 relative to each other, and will neglect the different values of
keywords FILENAME and FILTNAM1 (or their very existence).

fitsdiff command-line arguments can also be set using the environment variable
FITSDIFF_SETTINGS.  If the FITSDIFF_SETTINGS environment variable is present,
each argument present will override the corresponding argument on the command-
line unless the --exact option is specified.  The FITSDIFF_SETTINGS
environment variable exists to make it easier to change the behavior of
fitsdiff on a global level, such as in a set of regression tests.