Skip to content
Tutorials Center
My learning

Topics

Linux Command Reference ยท Shell Builtins

Bash local and readonly commands

Reference for the Bash local and readonly builtins: function-scoped variables, dynamic scoping, constants, readonly -f and -a, and common mistakes.

local declares a variable that exists only inside the function that declares it (and in functions that function calls). When the function returns, the variable is gone and any variable of the same name outside is visible again. Without local, every variable in a Bash function is global, which is the source of countless hard-to-find bugs.

readonly marks a variable or function as constant: it can no longer be reassigned or unset in that shell. Use it for configuration values that must not change.

Terminal
local [OPTION] NAME[=VALUE] ...
readonly [-aAf] [NAME[=VALUE] ...]
readonly -p

Try it

Bash local versus global variables

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 Constants with readonly

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
local [option] name[=value] ...
readonly [-aAf] [name[=value] ...]
readonly -p
Name Description
local name Create a local variable with no value (unset until assigned).
local name=value Create and assign. The value is evaluated before local runs, so local x=$(false) hides the failure status.
local -i, -a, -A, -n, -r, -x, -l, -u Same attribute options as declare.
readonly name[=value] Mark as read-only, optionally assigning first.
readonly -a / -A Mark arrays / associative arrays.
readonly -f name Make a function read-only.
readonly -p Print all read-only variables in reusable form.

Returns: 0 on success. local outside a function returns 1 with an error; changing a read-only variable returns 1.

Errors and edge cases: "readonly variable" errors in a non-interactive shell abort the script when it happens in an assignment statement under POSIX mode and just return a failed status otherwise. Read-only status cannot be removed; it ends with the shell.

Usage notes

  • Declare and assign separately when you need the exit status of a command substitution: local out; out=$(cmd) || return 1. The one-step local out=$(cmd) always returns local's status (0).
  • Dynamic scope. Bash uses dynamic scoping, not lexical: a function called from another function can see and modify the caller's locals. Name locals distinctively or keep helper functions pure.
  • Shadowing. local x creates a new empty variable, even when x is global. It does not inherit the outer value; use local x="$x" for that.
  • Arrays. local -a list=() and local -A map keep them out of the global namespace. Without -A, local map creates a scalar.
  • Constants at the top. Set configuration with readonly NAME=value early, so later code (or sourced files) cannot change it. Environment variables passed from outside can still be marked readonly afterwards.
  • No local in POSIX sh. dash and other POSIX shells accept local only as an extension (dash does), so #!/bin/sh scripts should avoid it or check carefully (Portability).
  • Interaction with unset. You cannot unset a read-only variable; an unset of a local one reveals the global again in some cases.
  • Loop variables are not local automatically: declare local i before for i in ... inside functions.
  • declare -r and readonly are equivalent. typeset is accepted for both.