What Does a Modulo Operator (%) Do in Python?

Let’s start with an enumerated illustration. A company wants to use the minimum number of requests for an online service. They also want to complete the work in parallel mode to minimize the total time without wasting any processor in an idle state.

When they use two parallel requests they find that in the last round only one processor is busy, which means the other one is idle. They decide to use three processors and distribute the number of requests evenly…to their surprise, they again still find one processor in the last round while the other two are idle. They use four processors the next time, then five, six…again to the result that only one processor is busy in the last round, all others are wasted. They finally use seven processors and all work equally, without any wasted cycle.

So, what can we learn about the least number of requests here?

Let’s dive right in!

Introduction#

The following conditional expressions can correctly test the value of n:

(
 (
  (n % 2) == (n % 3) == 
  (n % 4) == (n % 5) == 
  (n % 6) == 1
 )
 and (n % 7) == 0
)

What does the modulo % operator mean? This is the modulus operator that divides the left-hand side by the right-hand side and returns the remainder (not the quotient). We need to test the natural numbers until we reach the value of n such that the above condition is true. We can reduce iterations through the least common multiple of 2, 3, 4, 5, and 6. Let’s stick to the topic, not the example.

Similarly, we can implement the logic for the hours part depending upon the type of clock (12-hour or 24-hour).

Modulus is a valuable operation in computer science.

Practical uses of % for beginners#

Programs using the % operator#

The following basic programs are examples of other common uses of the modulus operator:

1. Returning a fraction instead of a decimal-point result of a division:

    # frac (7, 3) returns (2,1,3)
    # frac (6,  3) returns (2,0,3)
    # frac (6,0) returns (None,0,0)
    def frac(n, d):
        if d==0: return (None, 0, d)
        return (n//d, n%d, d)
   

2. Converting an elapsed time (given in seconds) into hours, minutes, and seconds:

    # time (5000) returns (1,23,20)
    # time (500) returns (0,8,20)
    # time (50) returns (0,0,50)
    def time(s):
        ss = s % 60
        s //= 60
        mm = s % 60
        s //= 60
        hh = s % 24
        return (hh, mm, ss)
   

3. The progress is only reported every $n^{th}$ time through the loop (to do something every $n^{th}$ iteration as opposed to doing on every iteration):

    # loop (70) prints 0,10,20,30,40,50,60,69
    # loop (30) prints 0,10,29,29
    # loop (15) prints 0,10,14
    def loop(s):
        for i in range(s):
            if i%10 == 0:
                print(i,end=',')
        print(i)
   

4. Reversing the digits in a number.

    # rev (1579) returns 9751
    # rev (234) returns 432
    # rev (60) returns 6
    def rev(n):
        r = 0
        while n>0:
            d = n % 10
            r = r * 10 + d
            n //= 10
        return r
   

5. Converting an integer in base 10 (decimal) to another base:

    # octa (255) returns 377
    # octa (63) returns 77
    # octa (7) returns 7
    def octa(n):
        b = 8
        t = 1
        r = 0
        while n>0:
            d = n % b
            r = t * d + r
            t = t * 10
            n //= 8
        return r
   

6. Converting a linear array to a matrix structure:

    # a1to2 ([10,20,30,40]) returns [[10, 20], [30, 40]]
    # a1to2 ([10,20,30,40,50]) returns [[10, 20], [30, 40], [50, 0]]
    # a1to2 ([10,20,30,40,50,60,70,80]) returns [[10, 20], [30, 40], [50, 60], [70, 80]]
    def a1to2(a1):
        s = len(a1)
        cols = int(s ** 0.5)
        rows = s // cols
        if rows*cols < s: rows = rows+1
        print(rows,cols)
        a2 = [[0 for i in range(cols)] for j in range(rows)]
        for i in range(s):
            r = i // cols
            c = i % cols
            a2[r][c] = a1[i]
        return a2
   

7. Computing the greatest common divisor:

    # gcd (12340,236) returns 4
    # gcd (10,20) returns 10
    # gcd (20,10) returns 10
    def gcd(a,b):
        if (a>b): x,y = a,b 
        else: x,y=b,a
        while y!=0:
            r = x % y
            x = y
            y = r
        return x
   

8. Computing the least common multiple:

    # lcm (20,30) returns 60
    # lcm (15,20) returns 60
    # lcm (30,7) returns 210
    def lcm(a,b):
        if (a>b): x,y = a,b 
        else: x,y=b,a
        l = y
        while l % x > 0:
            l = l + y
        return l
   

9. Testing if a number is prime or composite:

    # is_prime (20) returns False
    # is_prime (19) returns True
    # is_prime (21) returns False
    def is_prime(n):
        if n<2: return False
        r = int(n**0.5)+1
        for i in range(2,r):
            if n % i == 0: return False
        return True;
   

Modular arithmetic is used in number theory, group theory, and cryptography.

Peculiarities of % operator in Python#

The divmod() receives a number n and divisor d as parameters and returns a quotient q and a remainder r as results. The sign of the remainder depends on the sign of the divisor:

• A positive divisor results in a positive remainder.
• A negative divisor results in a negative remainder.

The following table shows a comparison of positive and negative divisors in Python, along with the reasoning.

Behavior of % for int vs. Decimal#

So what does the modulo ‘%’ operator do for decimal type objects? In Python, the result of the % operator for Decimal type objects is different from the result of the % operator for simple integers.

The sign of the numerator is used with the result when the Decimal object is used as the operand. Otherwise, the sign of the denominator is used.

In the above code, we have demonstrated the change in the remainder due to the change in the sign of the denominator. The first group of statements uses the % operator while the other uses the divmod() function to show the quotient for clarity of the remainder value.

In the above code, the result carries the sign of the numerator used in the expression. The remainder value results from simple (unsigned) values of operands without following the rule q * d + r == n.

Be cautious when using the Decimal objects with the % operator in Python. The result is different from that of simple integers.

Understanding the sign rule and the modulo identity#

One of the most common mistakes beginners make is misunderstanding how Python’s modulo operator behaves with negative numbers. Unlike some other languages, Python’s % operator ensures that the result always has the same sign as the divisor.

For example:

This might look confusing at first, but Python guarantees the following identity:

This identity holds true for all integer and floating-point modulo operations. Understanding it helps you reason about the result — no matter the signs of the operands.

Using divmod() for cleaner code#

In many cases, you might need both the quotient and the remainder from a division. Instead of calling // and % separately, Python offers the built-in divmod() function, which returns both in one step:

This is equivalent to writing:

…but it’s cleaner and often more efficient. This makes divmod() a great choice when you care about both results at once — for example, in number theory problems, pagination logic, or custom hashing functions.

Modulo with floats (and what isn’t supported)#

The % operator works with floats just like it does with integers:

It still follows the same identity and sign rules. However, keep in mind:

• Using % with complex numbers is not supported and will raise a TypeError.

• If you need to perform modulo operations on complex values, you’ll need to implement them manually.

% vs math.fmod() vs math.remainder()#

Python’s % isn’t the only way to compute a remainder. The math module provides two alternatives — and they behave slightly differently.

Here’s how they differ:

Understanding these differences is crucial when you’re working with low-level math, geometry, or scientific applications.

Behavior differences from other programming languages#

If you’re coming from C, C++, or JavaScript, you might notice that Python’s % behaves differently. Many other languages define the remainder based on the dividend’s sign, but Python bases it on the divisor’s.

This difference is intentional — it makes % behave consistently with the // operator and the modulo identity. If you’re porting code from another language, be mindful of this distinction.

Using modulo with NumPy arrays#

If you’re working with scientific or data-heavy applications, you’ll likely use NumPy. The good news: % behaves the same way on arrays.

• np.remainder() and the % operator behave like Python’s built-in modulo (sign of divisor).

• np.fmod() behaves like math.fmod() (sign of dividend).

This distinction becomes especially important in signal processing, data science, and numerical simulations.

Edge cases and errors to know#

There are a few common pitfalls you should be aware of when using the modulo operator:

• Division by zero: x % 0 raises a ZeroDivisionError.

• Custom types: If you define a class with __mod__, % can be overloaded.

• String formatting: % is also used in old-style string formatting — e.g., "Hello %s" % name.
  Although still supported, f-strings (f"Hello {name}") are preferred today.

Understanding these edge cases helps you write safer, more predictable code.

Wrapping up and next steps#

The modulus operator in Python is represented with the % operator. There are other built-in functions like divmod() that can be used to compute the remainder as a result of division. For simple integers, Python guarantees q * d + r == n for q, r = divmod(n, d). The result of the % operator differs if the operands are the objects of the Decimal type.

Happy learning!