Skip to content
Tutorials Center
My learning

Topics

Lesson 41 of 95 ยท Shell Scripting

Arrays and Associative Arrays

Learn Bash indexed and associative arrays: create, append, slice, loop with quotes, mapfile, declare -A, counting, passing arrays to functions and common pitfalls.

A plain shell variable holds one string. The moment you need a list (the files to process, the arguments to forward to another command, the lines of a file, a table of names and values) strings stop being enough. If you store a list in a string and split it later, any item that contains a space breaks. Bash solves this with two kinds of variables that hold many values: indexed arrays (numbered positions) and associative arrays (named keys, like a dictionary).

In this lesson you will learn how to create and change both kinds, the quoting rules ("${arr[@]}") that keep every element intact, how to slice, copy and filter arrays, how to fill them with mapfile, how to count and look things up with declare -A, how to pass arrays to functions, and the traps that make professionals nervous.

Arrays are a Bash (and ksh, zsh) feature. They do not exist in POSIX sh. Associative arrays need Bash 4 or newer; macOS still ships Bash 3.2 by default, which has only indexed arrays. See POSIX sh, Portability and Compatibility.

Indexed arrays

Create an array with parentheses, one element per word. Elements are numbered from 0. You read one element with ${arr[index]}, count them with ${#arr[@]}, and append with +=.

Bash Creating, reading and changing 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.

Points to note:

  • "cherry pie" is one element because it is quoted. The braces ${...} are required for any array access; $fruits[2] would be the value of $fruits followed by the text [2].
  • ${fruits[-1]} is the last element (Bash 4.3 and newer). ${#fruits[@]} is the number of elements, while ${#fruits[2]} is the number of characters in element 2.
  • $fruits without an index means ${fruits[0]}, a frequent source of bugs when someone expects the whole list.
  • Indexes do not have to be contiguous. We set fruits[10], so the array is sparse: the count is 6, but the indexes are 0 1 2 3 4 10. ${!fruits[@]} lists the used indexes.
  • unset 'fruits[1]' removes one element but does not renumber the others, leaving a hole at index 1. Quote the argument so the shell does not treat [1] as a glob. To re-pack an array: fruits=("${fruits[@]}").
  • declare -p name prints a variable in a re-usable form, the best debugging tool for arrays.
  • A normal variable behaves like an array with one element: x=hello; x[1]=world makes it a two-element array.

The quoting rules: "${arr[@]}"

This is the most important part of this lesson. There are four ways to expand all elements, and only one is correct for almost every use:

Form Result
"${arr[@]}" Each element as its own word, spaces preserved. Use this.
"${arr[*]}" All elements joined into one word, separated by the first character of IFS (a space by default)
${arr[@]} Elements, then word-split and globbed again: elements with spaces break
${arr[*]} Same as the above, with the same problems
Bash Why quoting matters

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.

You can see that the unquoted version turned three files into five words. "${arr[@]}" behaves exactly like "$@" does for the script's arguments: perfect forwarding. Use "${arr[*]}" only when you want one string, typically with a custom separator: (IFS=,; echo "${files[*]}") joins with commas (the subshell keeps the changed IFS from leaking). Parameter-expansion operators apply to each element: ${files[@]/.txt/.bak} replaced the extension everywhere (Parameter Expansion and String Handling).

Passing an array as command arguments is the main reason arrays exist: rsync "${opts[@]}" src dest, grep "${patterns[@]}", docker run "${args[@]}". Building a command in an array is the safe replacement for building it as a string and calling eval.

Slicing, copying and common operations

${arr[@]:offset:length} slices an array the same way ${string:offset:length} slices a string. A copy is made by expanding all elements into a new array, which also lets you concatenate.

Bash Slices, copies, filters and searching

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.

Notes:

  • Write a space before a negative offset, as in ${nums[@]: -2}, otherwise Bash reads it as the "default value" operator :-.
  • copy=("${nums[@]}") is the only correct way to duplicate an array. copy=$nums would copy only the first element.
  • Bash has no built-in sort or search for arrays. The usual ways are a loop, or piping the elements through sort (one per line) and reading them back with mapfile. That only works for elements without newlines.
  • has shows the pattern for "is this value in the list?". Sending an array to a function is covered further down.
  • Operators like ${words[@]^} (capitalize the first letter, ${words[@]^^} for all letters) work per element.

Filling arrays: mapfile and friends

The built-in mapfile (also named readarray) reads lines from standard input straight into an array, one line per element. -t strips the trailing newline from each. It is the safe replacement for arr=($(cat file)) which splits on every space.

Bash mapfile, read -a and globs into arrays

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.

  • The blank third line of lines.txt became an empty element [], and the file's 4 lines gave 4 elements.
  • Without -t, each element keeps its newline, which usually is not what you want.
  • -n 2 limits how many lines are read. -s N skips lines. -d '' reads NUL-terminated records, the safe way to take in find -print0 output (Bash 4.4+).
  • read -r -a splits one line into an array using IFS as the separator, with a here-string <<< as input (Here-Documents, Here-Strings and Input).
  • bad=($line) is the unquoted-expansion trap: it splits at whitespace and expands globs. Three words came out of the string x y z. Only use it when you want exactly that behaviour.
  • A glob is the correct way to put file names into an array: star=(*.txt). Combine with shopt -s nullglob so an unmatched pattern gives an empty array, not the pattern text (Loops).
  • When you use mapfile in a pipeline (cmd | mapfile -t arr) the array fills in a subshell and is lost. Use < <(cmd) instead (Subshells, Groups and Environment).

Associative arrays

An associative array maps string keys to values. It must be declared with declare -A before use. Indexing works the same as before, with a key instead of a number.

Bash declare -A: lookups, counting and sorted output

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.

What happens here:

  • ${!age[@]} lists the keys, ${age[@]} the values, ${#age[@]} the number of entries. Keys with spaces need quotes (age["carol lee"]), and they must be quoted in ${age[$k]} loops too.
  • Test for a key with [[ -v age[bob] ]], not by looking at the value: a key may exist with an empty value. A missing key expands to an empty string, or to a default via ${age[zed]:-unknown}.
  • Iteration order is not defined. Bash walks the keys in hash order, which looks random and can differ between versions. If the output order matters, sort the keys, as shown, or use the pattern sort -k2,2nr to rank by count.
  • The counting idiom (( freq[$w]++ )) works because a missing entry counts as 0 in arithmetic. It is the shell version of GROUP BY word, COUNT(*). Inside (( )), a status of 1 appears for the first increment (old value 0), so avoid it under set -e (see Arithmetic and Numbers).
  • m[01] and m[1] are two keys: associative keys are plain strings.
  • Forgetting declare -A is silent. plain[foo]=1 created an indexed array where foo is evaluated as arithmetic, a variable that is not set, hence 0. Both assignments wrote to index 0 and the second won. This is a classic bug on systems with an old Bash too.
  • Assign several pairs at once with declare -A color=([red]="#f00" ...). In Bash 5, declare -p shows the result in a re-usable format.

Passing arrays to functions

A function sees its arguments as a flat list, so my_func "${list[@]}" passes every element as a separate argument. To let a function change an array or return one, hand it the array's name and use a nameref (Functions).

Bash Arrays and functions, records and a fake 2D grid

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.

  • Passing "${list[@]}" hands the function a copy of each element; it cannot change the original. modify receives the name list and edits through the nameref.
  • Arrays are not first-class values. You cannot return one, put one in another array, or write arr2=$arr1. The tricks are namerefs, global variables, or printing elements and reading them back with mapfile.
  • Composite keys (grid[$r,$c]) fake a two-dimensional table inside one associative array. For "arrays of records" use parallel arrays, as above, or associative arrays with prefixed keys (person_ann_city).
  • Associative arrays cannot be passed by expansion at all, since there is no "${m[@]}" that carries the keys. Pass the name.

Pitfalls checklist

  1. Forgetting the braces: $arr[0]. Use ${arr[0]}.
  2. Unquoted ${arr[@]} or $(cmd) in arr=($(cmd)): word splitting and globbing. Use quotes and mapfile.
  3. unset 'arr[i]' leaves a hole: re-pack with arr=("${arr[@]}").
  4. Using ${arr[*]} where you meant "${arr[@]}".
  5. Counting with ${#arr} (length of element 0) instead of ${#arr[@]}.
  6. Forgetting declare -A.
  7. Relying on the order of keys.
  8. Filling an array inside a pipeline: it is lost in the subshell.
  9. Needing data structures beyond lists and dictionaries: nested arrays, sets, structs. Consider awk, Python or a different tool.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Given a=("x y" z), what does for i in ${a[@]}; do echo "[$i]"; done print?

    Without quotes the elements are word-split, so the element with a space becomes two words. Use "${a[@]}" to keep every element intact.
  2. 2. How do you get the number of elements in the array arr?

    ${#arr[@]} is the element count. ${#arr} is only the length of element 0 as a string.
  3. 3. What is the difference between "${arr[@]}" and "${arr[*]}"?

    Quoted [@] behaves like "$@": one word per element. Quoted [*] produces one string, handy for joining with a custom IFS.
  4. 4. A script has counts[apple]=3 without a prior declare -A counts. What does Bash do?

    Associative arrays must be declared with declare -A. Otherwise the subscript is evaluated as arithmetic (an unset name is 0), so every key writes to index 0.
  5. 5. Which command safely reads the lines of a file into an array?

    mapfile -t reads one line per element. The first form splits on every space, the third makes a single string, and the pipe version fills the array in a subshell that is lost.

Summary

  • Indexed arrays: a=(x y "z w"), ${a[0]}, ${a[-1]}, ${#a[@]} for the count, ${!a[@]} for the indexes, a+=(item) to append. Indexes can have holes.
  • Always expand with "${a[@]}"; use "${a[*]}" only to join into one string, and avoid unquoted forms.
  • Slice with ${a[@]:offset:length}, copy with b=("${a[@]}"), and apply operators like ${a[@]/x/y} to every element.
  • Fill arrays with mapfile -t arr < file, read -r -a, globs ((*.txt)) and < <(cmd); avoid arr=($(cmd)).
  • Associative arrays need declare -A; test keys with [[ -v m[key] ]], list keys with ${!m[@]}, count with (( m[$k]++ )), and sort keys yourself because the order is undefined.
  • Functions receive elements as arguments; to modify an array or return one, pass the name and use local -n.
  • Arrays cannot nest and are not passed or returned by value.

Next: Script Arguments and Options