Modulo Assignment

The %= operator in Bash is the arithmetic modulo assignment operator. It performs an integer division of a variable’s current value by an evaluated right-hand expression, computes the remainder, and immediately assigns that remainder back to the left-hand variable. Functionally, the expression x %= y is the syntactic shorthand for x = x % y.

Syntax

The operator must be executed within a Bash arithmetic evaluation context, such as the ((...)) compound command, the let builtin, or arithmetic expansion $((...)).

# Using the arithmetic evaluation compound command
(( variable %= expression ))


# Using the let builtin
let "variable %= expression"


# Using arithmetic expansion (requires assignment to be evaluated)
: $(( variable %= expression ))

Technical Characteristics

• Integer Restriction: Bash arithmetic evaluates strictly as integers. Attempting to use floating-point numbers with the %= operator will result in a syntax error.
• Evaluation Order: The right-hand expression is fully evaluated before the modulo operation and subsequent assignment occur.
• Sign Semantics: Bash follows C99 semantics for modulo operations involving negative integers. The sign of the resulting remainder always matches the sign of the dividend (the left-hand variable), regardless of the sign of the divisor.
• Division by Zero: If the right-hand expression evaluates to 0, Bash aborts the specific arithmetic evaluation, prints an error message to stderr (division by 0), and causes the command to return an exit status of 1. This is not a fatal error; the script will continue executing normally unless the set -e (errexit) option is active.
• Exit Status: The exit status of the arithmetic command depends entirely on the final assigned value. If the result of the modulo operation is 0 (e.g., (( 10 %= 5 ))), the command returns an exit status of 1 (failure). If the assigned value is non-zero, it returns 0 (success). This is a vital detail, as an operation resulting in 0 can unexpectedly trigger set -e or alter control flow in if/while statements.

Execution Mechanics

Standard Evaluation:

x=14
(( x %= 5 )) 

# x is now 4 (14 divided by 5 leaves a remainder of 4)

# Exit status is 0 (success) because the assigned value is non-zero.

Expression Evaluation:

y=20
(( y %= 2 + 4 )) 

# y is now 2. The right side (2 + 4) evaluates to 6 first. 20 % 6 = 2.

Negative Integer Handling:

a=-14
(( a %= 5 ))

# a is now -4 (Sign matches the dividend 'a')

b=14
(( b %= -5 ))

# b is now 4 (Sign matches the dividend 'b')

Zero Result and Exit Status:

c=10
(( c %= 5 ))

# c is now 0 (10 % 5 = 0)

# Exit status is 1 (failure) because the assigned value is 0.

Implicit Initialization: If the left-hand variable is unset or null prior to the operation, Bash treats its initial value as 0 within the arithmetic context.

unset z
(( z %= 5 ))

# z is now 0 (0 % 5 = 0)

# Exit status is 1 (failure).

Master Bash with Deep Grasping Methodology!

Learn More