Python Modulus Operator Tutorial

The Python modulus operator % returns the remainder after division. It is one of the most useful tools in the language — small enough to fit on one line, powerful enough to appear in scheduling logic, game loops, data pipelines, and unit conversion routines. This tutorial covers how it works, how it handles negative numbers, how it differs from math.fmod(), and the precedence rules that trip up programmers who mix it with multiplication and division.

Whether you need to filter every third row in a dataset, wrap a playlist index, or convert a raw number of seconds into hours, minutes, and seconds, % makes the job straightforward. This tutorial covers the mechanics, the edge cases, the math.fmod() distinction that separates Python's behavior from C and JavaScript, the precedence rules, and the patterns that appear again and again in real Python code.

How the Modulus Operator Works

Division produces two values: a quotient and a remainder. Python's floor division operator // gives you the quotient; % gives you the remainder. The two are related by a simple identity:

# The modulus identity
# (a // b) * b + (a % b) == a

a = 17
b = 5

quotient  = a // b   # 3
remainder = a % b    # 2

print(quotient)   # 3
print(remainder)  # 2

# Verify the identity
print(quotient * b + remainder == a)  # True

Read 17 % 5 as: "17 divided by 5 is 3 with 2 left over." The % expression evaluates to that leftover value, 2.

A quick way to build intuition is to walk through several examples and observe the pattern:

When the dividend is smaller than the divisor, the quotient is zero and the remainder is the dividend itself. That is why 7 % 10 returns 7 — Python cannot fit even one copy of 10 into 7, so the entire value is leftover.

Common Uses of the % Operator

The modulus operator appears in a surprisingly wide variety of everyday programming tasks. The four patterns below cover the majority of situations you will encounter.

Even and Odd Detection

The most common use is determining whether a number is even or odd. An even number divided by 2 leaves no remainder; an odd number leaves 1.

def classify(n):
    if n % 2 == 0:
        return "even"
    return "odd"

print(classify(8))   # even
print(classify(13))  # odd
print(classify(0))   # even (zero is even)

Cyclic Indexing

Modulus is the standard way to keep an index within the bounds of a sequence. When the index reaches the end, % len(sequence) wraps it back to the beginning.

colors = ["red", "green", "blue"]

for i in range(9):
    color = colors[i % len(colors)]
    print(f"Item {i}: {color}")

# Item 0: red
# Item 1: green
# Item 2: blue
# Item 3: red   <-- wraps back
# Item 4: green
# ...

Divisibility Testing

When n % k == 0, k divides n evenly. This is the foundation of the classic FizzBuzz problem and many number-theory exercises.

for n in range(1, 21):
    if n % 15 == 0:
        print("FizzBuzz")
    elif n % 3 == 0:
        print("Fizz")
    elif n % 5 == 0:
        print("Buzz")
    else:
        print(n)

Rate-Limiting Repeated Actions

In a long loop you often want to run a side effect (print progress, flush a buffer, log a status) every n iterations without breaking the loop's structure. Checking i % n == 0 accomplishes exactly that.

records = list(range(1000))

for i, record in enumerate(records):
    process(record)
    if i % 100 == 0:           # log every 100 items
        print(f"Processed {i} records...")

Modulus with Negative Numbers and Floats

Python's behavior with negative operands surprises programmers coming from C or Java. In Python, the result of % always carries the sign of the divisor (the right operand), not the dividend. This is a deliberate design choice tied to floor division.

# Negative dividend, positive divisor
print(-7 % 3)    # 2  (NOT -1)

# Positive dividend, negative divisor
print(7 % -3)    # -2 (NOT 2)

# Both negative
print(-7 % -3)   # -1

# Verify the identity still holds
a, b = -7, 3
print((a // b) * b + (a % b) == a)  # True

The % operator also works with floats, though the result may include floating-point rounding imprecision. For integer-precision work, stick to integer operands.

print(7.5 % 2.5)   # 0.0
print(10.0 % 3.0)  # 1.0
print(1.1 % 0.3)   # 0.19999999999999996  (floating-point imprecision)

math.fmod(): The Other Remainder Function

Python ships a second remainder function in its standard library that behaves differently from % in one critical way: math.fmod(x, y) returns a result whose sign follows the dividend (x), not the divisor. This matches how C's fmod() works and is intentional. The Python documentation for math.fmod() explicitly states that the result has the same sign as the first argument.

import math

# % follows the sign of the DIVISOR (y)
print(-7 % 3)            # 2   (positive — matches divisor 3)
print(7 % -3)            # -2  (negative — matches divisor -3)

# math.fmod() follows the sign of the DIVIDEND (x)
print(math.fmod(-7, 3))  # -1.0  (negative — matches dividend -7)
print(math.fmod(7, -3))  # 1.0   (positive — matches dividend 7)

# For positive operands, both agree
print(17 % 5)            # 2
print(math.fmod(17, 5))  # 2.0

The practical rule: use % for integer work and for any situation where you want the result to stay non-negative when the divisor is positive (cyclic indexing, time conversion, even/odd checks). Use math.fmod() when interoperating with C libraries or when you specifically need the C-style truncation behavior with floats. Note that math.fmod() always returns a float, even when both inputs are integers.

Operator Precedence with %

In Python, % shares the same precedence level as *, /, and //. Operators at the same level evaluate left to right. This can produce surprising results when % is mixed with multiplication or division without parentheses.

# Left-to-right evaluation at same precedence
result = 4 * 10 % 12     # reads as (4 * 10) % 12 = 40 % 12 = 4
print(result)            # 4

# Adding parentheses changes meaning entirely
result = 4 * (10 % 12)   # reads as 4 * (10 % 12) = 4 * 10 = 40
print(result)            # 40

# % and // at the same level, left-to-right
print(100 % 30 // 4)     # (100 % 30) // 4 = 10 // 4 = 2
print(100 % (30 // 4))   # 100 % 7 = 2  (coincidentally the same here, but not always)

"The % (modulo) operator yields the remainder from the division of the first argument by the second." — Python Language Reference, Binary arithmetic operations (Python Software Foundation)

Python Learning Summary Points

1. The % operator returns the remainder after dividing the left operand by the right. For positive integer operands, the result is always in the range 0 to divisor - 1. The result can never be greater than or equal to the divisor.
2. The modulus identity (a // b) * b + (a % b) == a always holds, regardless of the signs of the operands.
3. Python's % result follows the sign of the divisor, not the dividend — this differs from C, Java, and JavaScript when negative numbers are involved.
4. math.fmod(x, y) follows the sign of the dividend instead, matching C behavior. It always returns a float. Use % for integer and cyclic work; use math.fmod() when C-compatible float behavior is required.
5. The four most common applications are: even/odd detection, cyclic indexing, divisibility testing, and rate-limiting repeated actions in loops.
6. The built-in divmod(a, b) returns (a // b, a % b) in a single call and is more efficient than computing the two values separately.
7. % shares precedence with *, /, and //. When mixing these operators in one expression, use explicit parentheses to make the evaluation order clear.

Mastering the modulus operator unlocks a pattern that recurs across data processing, game development, scheduling, and cryptography. Once you recognize when a problem involves remainders or cyclic behavior, % becomes your first instinct rather than an afterthought.