obsid redshift  X      Y     object
3102  0.32      4167  4085   Q1250+568-A
877   0.22      4378  3892   "Source 82"
This table can be read with the following:




    

>>> from astropy.io import ascii
>>> data = ascii.read("sources.dat")  
>>> print(data)                       
obsid redshift  X    Y      object
----- -------- ---- ---- -----------
 3102     0.32 4167 4085 Q1250+568-A
  877     0.22 4378 3892   Source 82
The first argument to the read() function can be the name of a file, a string
representation of a table, or a list of table lines. The return value
(data in this case) is a Table object.
By default, read() will try to guess the table format
by trying all of the supported formats.
Warning
Guessing the file format is often slow for large files because the reader
tries parsing the file with every allowed format until one succeeds.
For large files it is recommended to disable guessing with guess=False.
If guessing the format does not work, as in the case for unusually formatted
tables, you may need to give astropy.io.ascii additional hints about
the format.
To specify specific data types for one or more columns, use the converters
argument (see Converters for Specifying Dtype for details). For instance if the
obsid is actually a string identifier (instead of an integer) you can read
the table with the code below. This also illustrates using the preferred
Table interface for reading:
>>> from astropy.table import Table
>>> sources = """
... target observatory obsid
... TW_Hya Chandra     22178
... MP_Mus XMM         0406030101"""
>>> data = Table.read(sources, format='ascii', converters={'obsid': str})
<Table length=2>
target observatory   obsid
 str6      str7      str10
------ ----------- ----------
TW_Hya     Chandra      22178
MP_Mus         XMM 0406030101
Writing Tables#
The write() function provides a way to write a data table as a formatted ASCII
table.  Most of the input table Supported Formats for reading are also
available for writing. This provides a great deal of flexibility in the format
for writing.
The following shows how to write a formatted ASCII table using the write()
function:
>>> import numpy as np
>>> from astropy.io import ascii
>>> from astropy.table import Table
>>> data = Table()
>>> data['x'] = np.array([1, 2, 3], dtype=np.int32)
>>> data['y'] = data['x'] ** 2
>>> ascii.write(data, 'values.dat', overwrite=True)
The values.dat file will then contain:
It is also possible and encouraged to use the write functionality from
astropy.io.ascii through a higher level interface in the Data
Tables package (see Unified File Read/Write Interface for more details). For
example:
>>> data.write('values.dat', format='ascii', overwrite=True)
Attention
ECSV is recommended
For a reproducible ASCII version of your table, we recommend using the
ECSV Format. This stores all the table meta-data (in particular the
column types and units) to a comment section at the beginning while
maintaining compatibility with most plain CSV readers. It also allows storing
richer data like SkyCoord or multidimensional or
variable-length columns. ECSV is also supported in Java by STIL and
TOPCAT (see ECSV Format).
To write our simple example table to ECSV we use:
>>> data.write('values.ecsv', overwrite=True)  
The .ecsv extension is recognized and implies using ECSV (equivalent to
format='ascii.ecsv'). The values.ecsv file will then contain:
# %ECSV 1.0
# ---
# datatype:
# - {name: x, datatype: int32}
# - {name: y, datatype: int32}
# schema: astropy-2.0
Supported Formats#
A full list of the supported format values and corresponding format types
for ASCII tables is given below. The Write column indicates which formats
support write functionality, and the Fast column indicates which formats
are compatible with the fast Cython/C engine for reading and writing.
Format
Write
Description
aastex
AASTex: AASTeX deluxetable used for AAS journals
basic
Basic: Basic table with custom delimiters
Cds: CDS format table
commented_header
CommentedHeader: Column names in a commented line
Csv: Basic table with comma-separated values
daophot
Daophot: IRAF DAOphot format table
Ecsv: Enhanced CSV format (recommended)
fixed_width
FixedWidth: Fixed width
fixed_width_no_header
FixedWidthNoHeader: Fixed-width with no header
fixed_width_two_line
FixedWidthTwoLine: Fixed-width with second header line
HTML: HTML format table
Ipac: IPAC format table
latex
Latex: LaTeX table
Mrt: AAS Machine-Readable Table format
no_header
NoHeader: Basic table with no headers
QDP: Quick and Dandy Plotter files
Rdb: Tab-separated with a type definition header line
RST: reStructuredText simple format table
sextractor
SExtractor: SExtractor format table
Tab: Basic table with tab-separated values
Using astropy.io.ascii#
The details of using astropy.io.ascii are provided in the following sections:
Reading tables#
Reading Tables

Parameters for read()
Specifying Header and Data Location
Bad or Missing Values
Guess Table Format
Comments and Metadata
Converters for Specifying Dtype
Fortran-Style Exponents
Advanced Customization
Reading Large Tables in Chunks
How to Find and Fix Problems Reading a Table
Reading Gaia Data Tables
Performance Tips#
By default, when trying to read a file the reader will guess the format, which
involves trying to read it with many different readers. For better performance
when dealing with large tables, it is recommended to specify the format and any
options explicitly, and turn off guessing as well.
Example#
If you are reading a simple CSV file with a one-line header with column names,
the following:
read('example.csv', format='basic', delimiter=',', guess=False)  # doctest: +SKIP
can be at least an order of magnitude faster than:
read('example.csv')  # doctest: +SKIP