Skip to content
Tutorials Center
My learning

Topics

Linux Command Reference ยท Shell Builtins

Bash mapfile and readarray commands

Reference for the Bash mapfile builtin (readarray): load lines into an array, strip newlines with -t, skip lines, limit counts, use callbacks and custom delimiters.

mapfile reads lines from standard input (or a file descriptor) into an indexed array, one line per element. It replaces the slow while read loop plus arr+=("$line") and is the cleanest way to turn a command's output or a file into something you can index, count and loop over. readarray is an exact synonym.

It exists since Bash 4.0. By default each element keeps its trailing newline, so you almost always add -t to remove it.

Terminal
mapfile [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] [-t] [-u FD] [-C CALLBACK] [-c QUANTUM] [ARRAY]

Try it

Bash Lines into an array

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Skipping, limiting and custom delimiters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
mapfile [-d delim] [-n count] [-O origin] [-s count] [-t] [-u fd] [-C callback] [-c quantum] [array]
readarray [same options]
Name Description
array Name of the array to fill. Default: MAPFILE. The array is cleared first unless -O is used.
-t Remove the trailing delimiter (usually the newline) from each element.
-n count Read at most count lines (0 means all).
-s count Discard the first count lines.
-O origin Start assigning at index origin (default 0) without clearing the array.
-d delim Use the first character of delim instead of newline. An empty string means NUL.
-u fd Read from file descriptor fd instead of standard input.
-C callback Run callback INDEX LINE each time quantum lines have been read.
-c quantum Number of lines between callbacks (default 5000).

Returns: 0 on success; non-zero if the array is read-only, is not an indexed array or the descriptor is invalid.

Errors and edge cases: the callback runs before the line is assigned, and evaluating very large callbacks is slow. mapfile is not available in Bash 3 (the default on macOS) or in POSIX shells.

Usage notes

  • Use -t. Without it each element ends in a newline, which breaks comparisons and file names.
  • Never pipe into mapfile. cmd | mapfile arr fills the array in a subshell that disappears. Use mapfile arr < <(cmd), a file redirection or shopt -s lastpipe (shopt).
  • Whole files. mapfile -t lines < file is faster than a read loop for a file of thousands of lines, because the loop is done inside the shell. Binary data should use -d '' with NUL-separated input.
  • File names with newlines. Combine find -print0 (or sort -z) with -d '' as in the example; plain newline-separated reading breaks on such names.
  • Empty input leaves an empty array (${#arr[@]} is 0). A final line without a newline is still kept as an element.
  • Compared with read -a: read -a splits one line into words; mapfile splits many lines into elements.
  • Compared with arr=($(cmd)): that form splits on every space and expands wildcards. mapfile preserves each line exactly.
  • Memory. The whole input lives in memory. For huge files, stream with while IFS= read -r line (read).
  • Negative indexes such as ${arr[-1]} work in Bash 4.3 and later.