Skip to main content
`Ctrl`+`K`

# File Handling and Convenience Functions

## `open()`

astropy.io.fits.open(name, mode='readonly', memmap=None, save_backup=False, cache=True, lazy_load_hdus=None, ignore_missing_simple=False, *, use_fsspec=None, fsspec_kwargs=None, decompress_in_memory=False, **kwargs)

  Factory function to open a FITS file and return an `HDUList` object.

  Parameters:
    name `python:str`, python:file-like object or `pathlib.Path`

      File to be opened.

    mode `python:str`, optional

      Open mode, ‘readonly’, ‘update’, ‘append’, ‘denywrite’, or ‘ostream’. Default is ‘readonly’.

      If `name` is a file object that is already opened, `mode` must match the mode the file was opened with, readonly (rb), update (rb+), append (ab+), ostream (w), denywrite (rb)).

    memmap bool, optional

      Is memory mapping to be used? This value is obtained from the configuration item `astropy.io.fits.Conf.use_memmap`. Default is `True`.

    save_backup bool, optional

      If the file was opened in update or append mode, this ensures that a backup of the original file is saved before any changes are flushed. The backup has the same name as the original file with “.bak” appended. If “file.bak” already exists then “file.bak.1” is used, and so on. Default is `False`.

    cache bool, optional

      If the file name is a URL, `download_file` is used to open the file. This specifies whether or not to save the file locally in Astropy’s download cache. Default is `True`.

    lazy_load_hdus bool, optional

      To avoid reading all the HDUs and headers in a FITS file immediately upon opening. This is an optimization especially useful for large files, as FITS has no way of determining the number and offsets of all the HDUs in a file without scanning through the file and reading all the headers. Default is `True`.

      To disable lazy loading and read all HDUs immediately (the old behavior) use `lazy_load_hdus=False`. This can lead to fewer surprises–for example with lazy loading enabled, `len(hdul)` can be slow, as it means the entire FITS file needs to be read in order to determine the number of HDUs. `lazy_load_hdus=False` ensures that all HDUs have already been loaded after the file has been opened.

      Added in version 1.3.

    uint bool, optional

      Interpret signed integer data where `BZERO` is the central value and `BSCALE == 1` as unsigned integer data. For example, `int16` data with `BZERO = 32768` and `BSCALE = 1` would be treated as `uint16` data. Default is `True` so that the pseudo-unsigned integer convention is assumed.

    ignore_missing_end bool, optional

      Do not raise an exception when opening a file that is missing an `END` card in the last header. Default is `False`.

    ignore_missing_simple bool, optional

      Do not raise an exception when the SIMPLE keyword is missing. Note that io.fits will raise a warning if a SIMPLE card is present but written in a way that does not follow the FITS Standard. Default is `False`.

      Added in version 4.2.

    checksum bool, `python:str`, optional

      If `True`, verifies that both `DATASUM` and `CHECKSUM` card values (when present in the HDU header) match the header and data of all HDU’s in the file. Updates to a file that already has a checksum will preserve and update the existing checksums unless this argument is given a value of ‘remove’, in which case the CHECKSUM and DATASUM values are not checked, and are removed when saving changes to the file. Default is `False`.

    disable_image_compression bool, optional

      If `True`, treats compressed image HDU’s like normal binary table HDU’s. Default is `False`.

    do_not_scale_image_data bool, optional

      If `True`, image data is not scaled using BSCALE/BZERO values when read. Default is `False`.

    character_as_bytes bool, optional

      Whether to return bytes for string columns, otherwise unicode strings are returned, but this does not respect memory mapping and loads the whole column in memory when accessed. Default is `False`.

    ignore_blank bool, optional

      If `True`, the BLANK keyword is ignored if present. Default is `False`.

    scale_back bool, optional

      If `True`, when saving changes to a file that contained scaled image data, restore the data to the original type and reapply the original BSCALE/BZERO values. This could lead to loss of accuracy if scaling back to integer values after performing floating point operations on the data. Default is `False`.

    output_verify `python:str`

      Output verification option. Must be one of `"fix"`, `"silentfix"`, `"ignore"`, `"warn"`, or `"exception"`. May also be any combination of `"fix"` or `"silentfix"` with `"+ignore"`, `+warn`, or `+exception" (e.g. ``"fix+warn"`). See Verification Options for more info.

    use_fsspec bool, optional

      Use `fsspec.open` to open the file? Defaults to `False` unless `name` starts with the Amazon S3 storage prefix `s3://` or the Google Cloud Storage prefix `gs://`. Can also be used for paths with other prefixes (e.g., `http://`) but in this case you must explicitly pass `use_fsspec=True`. Use of this feature requires the optional `fsspec` package. A `ModuleNotFoundError` will be raised if the dependency is missing.

      Added in version 5.2.

    fsspec_kwargs `python:dict`, optional

      Keyword arguments passed on to `fsspec.open`. This can be used to configure cloud storage credentials and caching behavior. For example, pass `fsspec_kwargs={"anon": True}` to enable anonymous access to Amazon S3 open data buckets. See `fsspec`’s documentation for available parameters.

      Added in version 5.2.

    decompress_in_memory bool, optional

      By default files are decompressed progressively depending on what data is needed. This is good for memory usage, avoiding decompression of the whole file, but it can be slow. With decompress_in_memory=True it is possible to decompress instead the whole file in memory.

      Added in version 6.0.

  Returns:
    hdulist `HDUList`

      `HDUList` containing all of the header data units in the file.

## `writeto()`

astropy.io.fits.writeto(filename, data, header=None, output_verify='exception', overwrite=False, checksum=False)

  Create a new FITS file using the supplied data/header.

  Parameters:
    filename python:path-like object or python:file-like object

      File to write to. If opened, must be opened in a writable binary mode such as ‘wb’ or ‘ab+’.

    data `array` or `recarray` or `Group`

      data to write to the new file

    header `Header` `object`, optional

      the header associated with `data`. If `None`, a header of the appropriate type is created for the supplied data. This argument is optional.

    output_verify `python:str`

      Output verification option. Must be one of `"fix"`, `"silentfix"`, `"ignore"`, `"warn"`, or `"exception"`. May also be any combination of `"fix"` or `"silentfix"` with `"+ignore"`, `+warn`, or `+exception" (e.g. ``"fix+warn"`). See Verification Options for more info.

    overwrite bool, optional

      If `True`, overwrite the output file if it exists. Raises an `OSError` if `False` and the output file exists. Default is `False`.

    checksum bool, optional

      If `True`, adds both `DATASUM` and `CHECKSUM` cards to the headers of all HDU’s written to the file.

  Notes

  gzip, zip, bzip2 and lzma compression algorithms are natively supported. Compression mode is determined from the filename extension (‘.gz’, ‘.zip’, ‘.bz2’ or ‘.xz’ respectively). It is also possible to pass a compressed file object, e.g. `gzip.GzipFile`.

## `info()`

astropy.io.fits.info(filename, output=None, **kwargs)

  Print the summary information on a FITS file.

  This includes the name, type, length of header, data shape and type for each HDU.

  Parameters:
    filename python:path-like object or python:file-like object

      FITS file to obtain info from. If opened, mode must be one of the following: rb, rb+, or ab+ (i.e. the file must be readable).

    output python:file object, bool, optional

      A file-like object to write the output to. If `False`, does not output to a file and instead returns a list of tuples representing the HDU info. Writes to `sys.stdout` by default.

    **kwargs

      Any additional keyword arguments to be passed to `astropy.io.fits.open`. Note: This function sets `ignore_missing_end=True` by default.

## `printdiff()`

astropy.io.fits.printdiff(inputa, inputb, *args, **kwargs)

  Compare two parts of a FITS file, including entire FITS files, FITS `HDUList` objects and FITS `HDU` objects.

  Parameters:
    inputa `python:str`, `HDUList` `object`, or `HDU` `object`

      The filename of a FITS file, `HDUList`, or `HDU` object to compare to `inputb`.

    inputb `python:str`, `HDUList` `object`, or `HDU` `object`

      The filename of a FITS file, `HDUList`, or `HDU` object to compare to `inputa`.

    ext, extname, extver

      Additional positional arguments are for HDU specification if your inputs are string filenames (will not work if `inputa` and `inputb` are `HDU` objects or `HDUList` objects). They are flexible and are best illustrated by examples. In addition to using these arguments positionally you can directly call the keyword parameters `ext`, `extname`.

      By HDU number:

          printdiff('inA.fits', 'inB.fits', 0)      # the primary HDU
          printdiff('inA.fits', 'inB.fits', 2)      # the second extension HDU
          printdiff('inA.fits', 'inB.fits', ext=2)  # the second extension HDU

      By name, i.e., `EXTNAME` value (if unique). `EXTNAME` values are not case sensitive:

      > printdiff(‘inA.fits’, ‘inB.fits’, ‘sci’) printdiff(‘inA.fits’, ‘inB.fits’, extname=’sci’) # equivalent

      By combination of `EXTNAME` and `EXTVER` as separate arguments or as a tuple:

          printdiff('inA.fits', 'inB.fits', 'sci', 2)    # EXTNAME='SCI'
                                                         # & EXTVER=2
          printdiff('inA.fits', 'inB.fits', extname='sci', extver=2)
                                                         # equivalent
          printdiff('inA.fits', 'inB.fits', ('sci', 2))  # equivalent

      Ambiguous or conflicting specifications will raise an exception:

          printdiff('inA.fits', 'inB.fits',
                    ext=('sci', 1), extname='err', extver=2)

    **kwargs

      Any additional keyword arguments to be passed to `FITSDiff`.

  Notes

  The primary use for the `printdiff` function is to allow quick print out of a FITS difference report and will write to `sys.stdout`. To save the diff report to a file please use `FITSDiff` directly.

## `append()`

astropy.io.fits.append(filename, data, header=None, checksum=False, verify=True, **kwargs)

  Append the header/data to FITS file if filename exists, create if not.

  If only `data` is supplied, a minimal header is created.

  Parameters:
    filename python:path-like object or python:file-like object

      File to write to. If opened, must be opened for update (rb+) unless it is a new file, then it must be opened for append (ab+). A file or `GzipFile` object opened for update will be closed after return.

    data `array`, `Table`, or `Group`

      The new data used for appending.

    header `Header` `object`, optional

      The header associated with `data`. If `None`, an appropriate header will be created for the data object supplied.

    checksum bool, optional

      When `True` adds both `DATASUM` and `CHECKSUM` cards to the header of the HDU when written to the file.

    verify bool, optional

      When `True`, the existing FITS file will be read in to verify it for correctness before appending. When `False`, content is simply appended to the end of the file. Setting `verify` to `False` can be much faster.

    **kwargs

      Additional arguments are passed to:

      - `writeto` if the file does not exist or is empty. In this case `output_verify` is the only possible argument.

      - `open` if `verify` is True or if `filename` is a file object.

      - Otherwise no additional arguments can be used.

## `update()`

astropy.io.fits.update(filename, data, *args, **kwargs)

  Update the specified HDU with the input data/header.

  Parameters:
    filename python:path-like object or python:file-like object

      File to update. If opened, mode must be update (rb+). An opened file object or `GzipFile` object will be closed upon return.

    data `array`, `Table`, or `Group`

      The new data used for updating.

    header `Header` `object`, optional

      The header associated with `data`. If `None`, an appropriate header will be created for the data object supplied.

    ext, extname, extver

      The rest of the arguments are flexible: the 3rd argument can be the header associated with the data. If the 3rd argument is not a `Header`, it (and other positional arguments) are assumed to be the HDU specification(s). Header and HDU specs can also be keyword arguments. For example:

          update(file, dat, hdr, 'sci')  # update the 'sci' extension
          update(file, dat, 3)  # update the 3rd extension HDU
          update(file, dat, hdr, 3)  # update the 3rd extension HDU
          update(file, dat, 'sci', 2)  # update the 2nd extension HDU named 'sci'
          update(file, dat, 3, header=hdr)  # update the 3rd extension HDU
          update(file, dat, header=hdr, ext=5)  # update the 5th extension HDU

    **kwargs

      Any additional keyword arguments to be passed to `astropy.io.fits.open`.

## `getdata()`

astropy.io.fits.getdata(filename, *args, header=None, lower=None, upper=None, view=None, **kwargs)

  Get the data from an HDU of a FITS file (and optionally the header).

  Parameters:
    filename python:path-like object or python:file-like object

      File to get data from. If opened, mode must be one of the following rb, rb+, or ab+.

    ext

      The rest of the arguments are for HDU specification. They are flexible and are best illustrated by examples.

      No extra arguments implies the primary HDU:

          getdata('in.fits')

      Note

      Exclusive to `getdata`: if `ext` is not specified and primary header contains no data, `getdata` attempts to retrieve data from first extension HDU.

      By HDU number:

          getdata('in.fits', 0)      # the primary HDU
          getdata('in.fits', 2)      # the second extension HDU
          getdata('in.fits', ext=2)  # the second extension HDU

      By name, i.e., `EXTNAME` value (if unique):

          getdata('in.fits', 'sci')
          getdata('in.fits', extname='sci')  # equivalent

      Note `EXTNAME` values are not case sensitive

      By combination of `EXTNAME` and EXTVER`` as separate arguments or as a tuple:

          getdata('in.fits', 'sci', 2)  # EXTNAME='SCI' & EXTVER=2
          getdata('in.fits', extname='sci', extver=2)  # equivalent
          getdata('in.fits', ('sci', 2))  # equivalent

      Ambiguous or conflicting specifications will raise an exception:

          getdata('in.fits', ext=('sci',1), extname='err', extver=2)

    header bool, optional

      If `True`, return the data and the header of the specified HDU as a tuple.

    lower, upper bool, optional

      If `lower` or `upper` are `True`, the field names in the returned data object will be converted to lower or upper case, respectively.

    view `ndarray`, optional

      When given, the data will be returned wrapped in the given ndarray subclass by calling:

          data.view(view)

    **kwargs

      Any additional keyword arguments to be passed to `astropy.io.fits.open`.

  Returns:
    array `ndarray` or `recarray` or `Group`

      Type depends on the type of the extension being referenced.

      If the optional keyword `header` is set to `True`, this function will return a (`data`, `header`) tuple.

  Raises:
    `IndexError`

      If no data is found in searched HDUs.

## `getheader()`

astropy.io.fits.getheader(filename, *args, **kwargs)

  Get the header from an HDU of a FITS file.

  Parameters:
    filename python:path-like object or python:file-like object

      File to get header from. If an opened file object, its mode must be one of the following rb, rb+, or ab+).

    ext, extname, extver

      The rest of the arguments are for HDU specification. See the `getdata` documentation for explanations/examples.

    **kwargs

      Any additional keyword arguments to be passed to `astropy.io.fits.open`.

  Returns:
    header `Header` `object`

## `getval()`

astropy.io.fits.getval(filename, keyword, *args, **kwargs)

  Get a keyword’s value from a header in a FITS file.

  Parameters:
    filename python:path-like object or python:file-like object

      Name of the FITS file, or file object (if opened, mode must be one of the following rb, rb+, or ab+).

    keyword `python:str`

      Keyword name

    ext, extname, extver

      The rest of the arguments are for HDU specification. See `getdata` for explanations/examples.

    **kwargs

      Any additional keyword arguments to be passed to `astropy.io.fits.open`. Note: This function automatically specifies `do_not_scale_image_data = True` when opening the file so that values can be retrieved from the unmodified header.

  Returns:
    keyword value `python:str`, `python:int`, or `python:float`

## `setval()`

astropy.io.fits.setval(filename, keyword, *args, value=None, comment=None, before=None, after=None, savecomment=False, **kwargs)

  Set a keyword’s value from a header in a FITS file.

  If the keyword already exists, it’s value/comment will be updated. If it does not exist, a new card will be created and it will be placed before or after the specified location. If no `before` or `after` is specified, it will be appended at the end.

  When updating more than one keyword in a file, this convenience function is a much less efficient approach compared with opening the file for update, modifying the header, and closing the file.

  Parameters:
    filename python:path-like object or python:file-like object

      Name of the FITS file, or file object If opened, mode must be update (rb+). An opened file object or `GzipFile` object will be closed upon return.

    keyword `python:str`

      Keyword name

    value `python:str`, `python:int`, `python:float`, optional

      Keyword value (default: `None`, meaning don’t modify)

    comment `python:str`, optional

      Keyword comment, (default: `None`, meaning don’t modify)

    before `python:str`, `python:int`, optional

      Name of the keyword, or index of the card before which the new card will be placed. The argument `before` takes precedence over `after` if both are specified (default: `None`).

    after `python:str`, `python:int`, optional

      Name of the keyword, or index of the card after which the new card will be placed. (default: `None`).

    savecomment bool, optional

      When `True`, preserve the current comment for an existing keyword. The argument `savecomment` takes precedence over `comment` if both specified. If `comment` is not specified then the current comment will automatically be preserved (default: `False`).

    ext, extname, extver

      The rest of the arguments are for HDU specification. See `getdata` for explanations/examples.

    **kwargs

      Any additional keyword arguments to be passed to `astropy.io.fits.open`. Note: This function automatically specifies `do_not_scale_image_data = True` when opening the file so that values can be retrieved from the unmodified header.

## `delval()`

astropy.io.fits.delval(filename, keyword, *args, **kwargs)

  Delete all instances of keyword from a header in a FITS file.

  Parameters:
    filename python:path-like object or python:file-like object

      Name of the FITS file, or file object If opened, mode must be update (rb+). An opened file object or `GzipFile` object will be closed upon return.

    keyword `python:str`, `python:int`

      Keyword name or index

    ext, extname, extver

      The rest of the arguments are for HDU specification. See `getdata` for explanations/examples.

    **kwargs

      Any additional keyword arguments to be passed to `astropy.io.fits.open`. Note: This function automatically specifies `do_not_scale_image_data = True` when opening the file so that values can be retrieved from the unmodified header.