read.table in R: Syntax, Arguments and Examples

read.table() reads a delimited text file into an R data frame. It is the general function behind read.csv() and read.delim(), and its defaults differ from both: it splits on any white space, does not assume a header row, and treats # as a comment character. This guide covers the syntax, the arguments that cause most problems, a worked example and how to diagnose a failed read. Sources are the R reference manual and the R Data Import/Export manual (read 2026-11-08).

What read.table() is used for in research

Researchers use read.table() for plain-text data that is not comma-separated: instrument exports, space- or tab-aligned output from other programs, and small tables pasted into a script. The function returns a data frame (see data frames in R). If your file is a standard CSV, reading CSV files into R is the shorter route; for the wider set of import options, see how to import data in R and how to load data into R.

Install or access

read.table() belongs to the utils package, which ships with base R and is attached at startup. Nothing needs to be installed. Download R from the Comprehensive R Archive Network (CRAN, cran.r-project.org) and open the manual for any function with ?read.table.

Step-by-step: read a file with read.table()

1. Check the file’s layout. Note the separator (white space, tab, semicolon), whether the first line holds column names, and whether any lines start with a comment character.
2. Set the working directory or give a full path. getwd() shows where R is looking.
3. Call the function and state the header explicitly. The Data Import/Export manual recommends specifying the header argument explicitly rather than relying on auto-detection:

   df <- read.table("measurements.txt", header = TRUE, sep = "")

4. Inspect the result with str(df) and head(df).

Worked example with the text argument

The text argument reads from a character string when file is missing, which lets you test arguments without creating a file:

df <- read.table(text = "id value a 1 b 2", header = TRUE) str(df)

Because sep defaults to "" (any white space), the two columns are split at the space. The id column is read as character and value as integer, and stringsAsFactors defaults to FALSE in the documented usage.

Arguments and how read.table() differs from read.csv() and read.delim()

The reference manual describes read.csv() and read.delim() as variants of read.table() with different defaults. Defaults that matter most:

Argument	read.table()	read.csv()	read.delim()
header	FALSE (auto-set TRUE only if the first row has one fewer field than the columns)	TRUE	TRUE
sep	"" (any white space)	","	"t"
quote	""'" (double and single quotes)	"""	"""
fill	!blank.lines.skip	TRUE	TRUE
comment.char	"#"	"" (none)	"" (none)

Other arguments you will use often, as described in the manual:

• skip: number of lines to skip before reading data.
• nrows: maximum number of rows to read; negative values are ignored.
• na.strings: strings to read as NA (default "NA").
• colClasses: the class of each column; the default NA lets R decide.
• row.names and col.names: set row or column names instead of taking them from the file.

Output and how to read it

The value is a data frame. Empty input is an error unless col.names is supplied. The header rule has one side effect worth knowing: if you leave header unspecified and the first line has one fewer field than the rest, R sets header = TRUE and uses the first column as row names. That is why the manual’s advice to set header explicitly avoids surprises. Check column classes with str(df); a numeric column read as character usually signals a stray non-numeric string, a different decimal mark (see dec) or an unquoted symbol.

Troubleshooting

Rows have different numbers of fields

Use count.fields() to see how many fields R finds on each line; the Data Import/Export manual recommends it for diagnosing wrong option choices:

table(count.fields("measurements.txt", sep = ""))

If the counts differ, set fill = TRUE so blank fields are added to short rows, or fix the file.

Lines are cut short or silently dropped

The default comment character is #, and everything after it on a line is ignored. If # is part of your data, set comment.char = "". Likewise an apostrophe inside an unquoted text field is treated as an opening quote by default; set quote = "" to disable quoting altogether.

Reading a large file is slow

The Data Import/Export manual advises specifying comment.char, colClasses and nrows (a slight overestimate of the row count is better than an underestimate). It also states that read.table() is inefficient for very large numeric matrices and recommends scan() for them; in its 200 by 2000 benchmark, scan() took about 1 second against 10 seconds for default read.table() and 7 seconds with colClasses and nrows set.

Free alternatives

Function	Package	What the documentation says it is for
read.csv(), read.delim()	utils (base R)	Wrappers of read.table() with comma and tab defaults.
scan()	base R	Lower-level reader; recommended by the Data Import/Export manual for large numeric matrices.

All of these ship with R and are free software. Add-on packages for reading delimited files exist on CRAN; check each package’s own documentation before relying on its defaults.

FAQ

What does read.table() return?

A data frame. If the input is empty, it raises an error unless col.names is given.

What is the difference between read.table() and read.csv()?

read.csv() calls read.table() with header = TRUE, sep = ",", fill = TRUE and no comment character. read.table() defaults to white-space separation, header = FALSE and comment.char = "#".

Why are my column names read as the first row of data?

Because header defaults to FALSE. Set header = TRUE.

Can I read data typed directly into a script?

Yes. Pass a character string to the text argument instead of a file name.

Sources

• R Core Team, read.table, R reference manual (utils package): stat.ethz.ch/R-manual/R-patched/library/utils/html/read.table.html, read 2026-11-08.
• R Core Team, R Data Import/Export, sections 2.1 and 2.4: cran.r-project.org/doc/manuals/r-release/R-data.html, read 2026-11-08.