Bash Associative Arrays: A Practical Guide to Key-Value Mappings in Shell Scripts

The Problem: Managing Dynamic Mappings in Shell Scripts

When a script needs to maintain a dynamic set of key-value pairs—configuration lookups, status tracking, or data transformations—plain indexed arrays become unwieldy. You end up with parallel arrays or repeated case statements, both of which are error-prone and hard to maintain. Bash 4.0+ introduced associative arrays to solve this, providing a native key-value store that behaves like a small in-memory database.

Declaring and Using an Associative Array

Start by declaring the array with declare -A. The -A flag tells Bash to treat the variable as an associative array rather than a numbered one:

declare -A user_roles

Assign values using bracket syntax where the key is a string:

user_roles['alice']='admin'
user_roles['bob']='user'
user_roles['charlie']='guest'

Retrieve a value with the same bracket notation:

echo "Alice's role: ${user_roles['alice']}"

If the key doesn't exist, Bash returns an empty string. This makes error handling straightforward but requires you to check for missing keys explicitly.

Iterating Over Keys and Values

To process all entries, use ${!array[@]} to get the list of keys:

for user in "${!user_roles[@]}"; do
    echo "User: $user, Role: ${user_roles[$user]}"
done

This pattern is useful for generating reports, validating data, or transforming entries. If you need just the values, reference ${array[@]} directly:

for role in "${user_roles[@]}"; do
    echo "Role assigned: $role"
done

Checking Key Existence

Before accessing a key, verify it exists. The -v test operator (Bash 4.2+) is the cleanest approach:

if [[ -v user_roles['dave'] ]]; then
    echo "Dave's role: ${user_roles['dave']}"
else
    echo "No role found for Dave"
fi

For older Bash versions, use the parameter expansion trick:

if [[ -n ${user_roles['dave']+x} ]]; then
    echo "Key exists"
fi

The +x suffix substitutes x if the key is set, allowing existence checks without triggering the default empty-string behavior.

Worked Example: Service Status Tracker

Consider a monitoring script that tracks service health and reports issues:

#!/bin/bash
# Requires Bash 4.0+

declare -A service_status

# Simulate status checks
service_status['nginx']='running'
service_status['mysql']='running'
service_status['redis']='stopped'
service_status['postgresql']='running'

# Generate report
echo "Service Health Report"
echo "====================="
for svc in "${!service_status[@]}"; do
    status=${service_status[$svc]}
    if [[ "$status" != 'running' ]]; then
        echo "ALERT: $svc is $status"
    fi
done

Running this script outputs:

ALERT: redis is stopped

This approach scales cleanly: adding new services requires only a new assignment, not modifying conditional logic.

Trade-offs and Limitations

Associative arrays store keys and values exclusively as strings. Numeric operations require explicit conversion via expr or arithmetic expansion. More critically, exporting these arrays to child processes via export is unreliable—Bash may serialize them as a single string rather than preserving the key-value structure.

Older systems running Bash 3.x lack this feature entirely. Check compatibility with:

bash --version

Version 4.0 or higher is required. On systems where you cannot upgrade, consider using files or external tools like awk for key-value storage.

Actionable Next Steps

Verify your Bash version before using associative arrays. Create a small test script that declares an array, assigns a key-value pair, and echoes the result. Once confirmed working, refactor any parallel indexed arrays or case-based lookups into associative array form. This reduces maintenance burden and makes scripts more readable.