get_pkg_data_fileobj, package=None, encoding=None, cache=True)[source]

Retrieves a data file from the standard locations for the package and provides the file as a file-like object that reads bytes.


Name/location of the desired data file. One of the following:

  • The name of a data file included in the source distribution. The path is relative to the module calling this function. For example, if calling from astropy.pkname, use 'data/file.dat' to get the file in astropy/pkgname/data/file.dat. Double-dots can be used to go up a level. In the same example, use '../data/file.dat' to get astropy/data/file.dat.

  • If a matching local file does not exist, the Astropy data server will be queried for the file.

  • A hash like that produced by compute_hash can be requested, prefixed by ‘hash/’ e.g. ‘hash/34c33b3eb0d56eb9462003af249eff28’. The hash will first be searched for locally, and if not found, the Astropy data server will be queried.

packagestr, optional

If specified, look for a file relative to the given package, rather than the default of looking relative to the calling module’s package.

encodingstr, optional

When None (default), returns a file-like object with a read method returns str (unicode) objects, using locale.getpreferredencoding as an encoding. This matches the default behavior of the built-in open when no mode argument is provided.

When 'binary', returns a file-like object where its read method returns bytes objects.

When another string, it is the name of an encoding, and the file-like object’s read method will return str (unicode) objects, decoded from binary using the given encoding.


If True, the file will be downloaded and saved locally or the already-cached local copy will be accessed. If False, the file-like object will directly access the resource (e.g. if a remote URL is accessed, an object like that from urllib.request.urlopen is returned).


An object with the contents of the data file available via read function. Can be used as part of a with statement, automatically closing itself after the with block.

urllib2.URLError, urllib.error.URLError

If a remote file cannot be found.


If problems occur writing or reading a local file.

See also


returns the contents of a file or url as a bytes object


returns a local name for a file containing the data


This will retrieve a data file and its contents for the astropy.wcs tests:

>>> from import get_pkg_data_fileobj
>>> with get_pkg_data_fileobj('data/3d_cd.hdr',
...                           package='astropy.wcs.tests') as fobj:
...     fcontents =

This next example would download a data file from the astropy data server because the allsky/allsky_rosat.fits file is not present in the source distribution. It will also save the file locally so the next time it is accessed it won’t need to be downloaded.:

>>> from import get_pkg_data_fileobj
>>> with get_pkg_data_fileobj('allsky/allsky_rosat.fits',
...                           encoding='binary') as fobj:  
...     fcontents =
Downloading [Done]

This does the same thing but does not cache it locally:

>>> with get_pkg_data_fileobj('allsky/allsky_rosat.fits',
...                           encoding='binary', cache=False) as fobj:  
...     fcontents =
Downloading [Done]