Skip to main content
`Ctrl`+`K`

# HDU Lists

## `HDUList`

class astropy.io.fits.HDUList(hdus=[], file=None)

  Bases: `list`, `_Verify`

  HDU list class. This is the top-level FITS object. When a FITS file is opened, a `HDUList` object is returned.

  Construct a `HDUList` object.

  Parameters:
    hdus HDU or python:sequence thereof, optional

      The HDU object(s) to comprise the `HDUList`. Should be instances of HDU classes like `ImageHDU` or `BinTableHDU`.

    file python:file-like object, `bytes`, optional

      The opened physical file associated with the `HDUList` or a bytes object containing the contents of the FITS file.

  append(hdu)

    Append a new HDU to the `HDUList`.

    Parameters:
      hdu HDU

        HDU to add to the `HDUList`.

  close(output_verify='exception', verbose=False, closed=True)

    Close the associated FITS file and memmap object, if any.

    Parameters:
      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.

      verbose bool

        When `True`, print out verbose messages.

      closed bool

        When `True`, close the underlying file object.

  copy()

    Return a shallow copy of an HDUList.

    Returns:
      copy `HDUList`

        A shallow copy of this `HDUList` object.

  fileinfo(index)

    Returns a dictionary detailing information about the locations of the indexed HDU within any associated file. The values are only valid after a read or write of the associated file with no intervening changes to the `HDUList`.

    Parameters:
      index `python:int`

        Index of HDU for which info is to be returned.

    Returns:
      fileinfo `python:dict` or `python:None`

        The dictionary details information about the locations of the indexed HDU within an associated file. Returns `None` when the HDU is not associated with a file.

        Dictionary contents:

        Key | Value
        --- | ---
        file | File object associated with the HDU
        filename | Name of associated file object
        filemode | Mode in which the file was opened (readonly, update, append, denywrite, ostream)
        resized | Flag that when `True` indicates that the data has been resized since the last read/write so the returned values may not be valid.
        hdrLoc | Starting byte location of header in file
        datLoc | Starting byte location of data block in file
        datSpan | Data size including padding

  filename()

    Return the file name associated with the HDUList object if one exists. Otherwise returns None.

    Returns:
      filename `python:str`

        A string containing the file name associated with the HDUList object if an association exists. Otherwise returns None.

  flush(output_verify='fix', verbose=False)

    Force a write of the `HDUList` back to the file (for append and update modes only).

    Parameters:
      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.

      verbose bool

        When `True`, print verbose messages

  classmethod fromfile(fileobj, mode=None, memmap=None, save_backup=False, cache=True, lazy_load_hdus=True, ignore_missing_simple=False, **kwargs)

    Creates an `HDUList` instance from a file-like object.

    The actual implementation of `fitsopen()`, and generally shouldn’t be used directly. Use `open()` instead (and see its documentation for details of the parameters accepted by this method).

  classmethod fromstring(data, **kwargs)

    Creates an `HDUList` instance from a string or other in-memory data buffer containing an entire FITS file. Similar to `HDUList.fromfile()`, but does not accept the mode or memmap arguments, as they are only relevant to reading from a file on disk.

    This is useful for interfacing with other libraries such as CFITSIO, and may also be useful for streaming applications.

    Parameters:
      data `python:str`, :term:buffer-like, etc.

        A string or other memory buffer containing an entire FITS file. Buffer-like objects include `bytes`, `bytearray`, `memoryview`, and `ndarray`. It should be noted that if that memory is read-only (such as a Python string) the returned `HDUList`’s data portions will also be read-only.

      **kwargs `python:dict`

        Optional keyword arguments. See `astropy.io.fits.open()` for details.

    Returns:
      hdul `HDUList`

        An `HDUList` object representing the in-memory FITS file.

  index_of(key)

    Get the index of an HDU from the `HDUList`.

    Parameters:
      key `python:int`, `python:str`, `python:tuple` of (`python:str`, `python:int`) or HDU

        The key identifying the HDU. If `key` is a tuple, it is of the form `(name, ver)` where `ver` is an `EXTVER` value that must match the HDU being searched for.

        If the key is ambiguous (e.g. there are multiple ‘SCI’ extensions) the first match is returned. For a more precise match use the `(name, ver)` pair.

        If even the `(name, ver)` pair is ambiguous (it shouldn’t be but it’s not impossible) the numeric index must be used to index the duplicate HDU.

        When `key` is an HDU object, this function returns the index of that HDU object in the `HDUList`.

    Returns:
      index `python:int`

        The index of the HDU in the `HDUList`.

    Raises:
      `ValueError`

        If `key` is an HDU object and it is not found in the `HDUList`.

      `KeyError`

        If an HDU specified by the `key` that is an extension number, extension name, or a tuple of extension name and version is not found in the `HDUList`.

  info(output=None)

    Summarize the info of the HDUs in this `HDUList`.

    Note that this function prints its results to the console—it does not return a value.

    Parameters:
      output python:file-like object or 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.

  insert(index, hdu)

    Insert an HDU into the `HDUList` at the given `index`.

    Parameters:
      index `python:int`

        Index before which to insert the new HDU.

      hdu HDU

        The HDU object to insert

  pop(index=-1)

    Remove an item from the list and return it.

    Parameters:
      index `python:int`, `python:str`, `python:tuple` of (`python:str`, `python:int`), optional

        An integer value of `index` indicates the position from which `pop()` removes and returns an HDU. A string value or a tuple of `(string, int)` functions as a key for identifying the HDU to be removed and returned. If `key` is a tuple, it is of the form `(key, ver)` where `ver` is an `EXTVER` value that must match the HDU being searched for.

        If the key is ambiguous (e.g. there are multiple ‘SCI’ extensions) the first match is returned. For a more precise match use the `(name, ver)` pair.

        If even the `(name, ver)` pair is ambiguous the numeric index must be used to index the duplicate HDU.

    Returns:
      hdu HDU

        The HDU object at position indicated by `index` or having name and version specified by `index`.

  readall()

    Read data of all HDUs into memory.

  update_extend()

    Make sure that if the primary header needs the keyword `EXTEND` that it has it and it is correct.

  writeto(fileobj, output_verify='exception', overwrite=False, checksum=False)

    Write the `HDUList` to a new file.

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

        File to write to. If a file object, must be opened in a writeable mode.

      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

        When `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`.