How does the modulo (%) operator work on negative numbers in Python?

Here’s an explanation from Guido van Rossum:

http://python-history.blogspot.com/2010/08/why-pythons-integer-division-floors.html

Essentially, it’s so that a/b = q with remainder r preserves the relationships b*q + r = a and 0 <= r < b.

Modulo, equivalence classes for 4:

• 0: 0, 4, 8, 12… and -4, -8, -12…
• 1: 1, 5, 9, 13… and -3, -7, -11…
• 2: 2, 6, 10… and -2, -6, -10…
• 3: 3, 7, 11… and -1, -5, -9…

Here’s a link to modulo’s behavior with negative numbers. (Yes, I googled it)

There is no one best way to handle integer division and mods with negative numbers. It would be nice if a/b was the same magnitude and opposite sign of (-a)/b. It would be nice if a % b was indeed a modulo b. Since we really want a == (a/b)*b + a%b, the first two are incompatible.

Which one to keep is a difficult question, and there are arguments for both sides. C and C++ round integer division towards zero (so a/b == -((-a)/b)), and apparently Python doesn’t.

As pointed out, Python modulo makes a well-reasoned exception to the conventions of other languages.

This gives negative numbers a seamless behavior, especially when used in combination with the // integer-divide operator, as % modulo often is (as in math.divmod):

for n in range(-8,8):
    print n, n//4, n%4

Produces:

 -8 -2 0
 -7 -2 1
 -6 -2 2
 -5 -2 3

 -4 -1 0
 -3 -1 1
 -2 -1 2
 -1 -1 3

  0  0 0
  1  0 1
  2  0 2
  3  0 3

  4  1 0
  5  1 1
  6  1 2
  7  1 3

• Python % always outputs zero or positive*
• Python // always rounds toward negative infinity

_{* … as long as the right operand is positive. On the other hand 11 % -10 == -9}

I also thought it was a strange behavior of Python. It turns out that I was not solving the division well (on paper); I was giving a value of 0 to the quotient and a value of -5 to the remainder. Terrible… I forgot the geometric representation of integers numbers. By recalling the geometry of integers given by the number line, one can get the correct values for the quotient and the remainder, and check that Python’s behavior is fine. (Although I assume that you have already resolved your concern a long time ago).

It’s also worth to mention that also the division in python is different from C:
Consider

>>> x = -10
>>> y = 37

in C you expect the result

0

what is x/y in python?

>>> print x/y
-1

and % is modulo – not the remainder! While x%y in C yields

-10

python yields.

>>> print x%y
27

You can get both as in C

The division:

>>> from math import trunc
>>> d = trunc(float(x)/y)
>>> print d
0

And the remainder (using the division from above):

>>> r = x - d*y
>>> print r
-10

This calculation is maybe not the fastest but it’s working for any sign combinations of x and y to achieve the same results as in C plus it avoids conditional statements.

In python, modulo operator works like this.

>>> mod = n - math.floor(n/base) * base

so the result is (for your case):

mod = -5 - floor(-1.25) * 4
mod = -5 - (-2*4)
mod = 3

whereas other languages such as C, JAVA, JavaScript use truncation instead of floor.

>>> mod = n - int(n/base) * base

which results in:

mod = -5 - int(-1.25) * 4
mod = -5 - (-1*4)
mod = -1

If you need more information about rounding in python, read this.

Other answers, especially the selected one have clearly answered this question quite well. But I would like to present a graphical approach that might be easier to understand as well, along with python code to perform normal mathematical modulo in python.

Python Modulo for Dummies

Modulo function is a directional function that describes how much we have to move further or behind after the mathematical jumps that we take during division over our X-axis of infinite numbers.
So let’s say you were doing 7%3

So in forward direction, your answer would be +1, but in backward direction-

your answer would be -2. Both of which are correct mathematically.

Similarly, you would have 2 moduli for negative numbers as well. For eg: -7%3, can result both in -1 or +2 as shown –

Forward direction

---

Backward direction

---

In mathematics, we choose inward jumps, i.e. forward direction for a positive number and backward direction for negative numbers.

But in Python, we have a forward direction for all positive modulo operations. Hence, your confusion –

>>> -5 % 4 
3

>>> 5 % 4
1

Here is the python code for inward jump type modulo in python:

def newMod(a,b):
    res = a%b
    return res if not res else res-b if a<0 else res

which would give –

>>> newMod(-5,4)
-1

>>> newMod(5,4)
1

Many people would oppose the inward jump method, but my personal opinion is, that this one is better!!

You can use:

result = numpy.fmod(x,y)

it will keep the sign , see numpy fmod() documentation.

@Deekshant has explained it well using visualisation. Another way to understand %(modulo) is ask a simple question.

What is nearest smaller number to dividend that can be divisible by divisor on X-axis ?

Let’s have a look at few examples.

5 % 3 

5 is Dividend, 3 is divisor. If you ask above question 3 is nearest smallest number that is divisible by divisor. ans would be 5 – 3 = 2. For positive Dividend, nearest smallest number would be always right side of dividend.

-5 % 3

Nearest smallest number that is divisible by 3 is -6 so ans would be -5 – (-6) = 1

-5 %4

Nearest smallest number that is divisible by 4 is -8 so ans would be -5 – (-8) = 3

Python answers every modulo expression with this method. Hope you can understand next how expression would be going to execute.

It’s what modulo is used for. If you do a modulo through a series of numbers, it will give a cycle of values, say:

ans = num % 3

I attempted to write a general answer covering all input cases, because many people ask about various special cases (not just the one in OP, but also especially about negative values on the right-hand side) and it’s really all the same question.

What does a % b actually give us in Python, explained in words?

Assuming that a and b are either float and/or int values, finite (not math.inf, math.nan etc.) and that b is not zero….

The result c is the unique number with the sign of b, such that a - c is divisible by b and abs(c) < abs(b). It will be an int when a and b are both int, and a float (even if it is exactly equal to an integer) when either a or b is an int.

For example:

>>> -9 % -5
-4
>>> 9 % 5
4
>>> -9 % 5
1
>>> 9 % -5
-1

The sign preservation also works for floating-point numbers; even when a is divisible by b, it is possible to get distinct 0.0 and -0.0 results (recalling that zero is signed in floating-point), and the sign will match b.

Proof of concept:

import math

def sign(x):
    return math.copysign(1, x)

def test(a: [int, float], b: [int, float]):
    c = a % b
    if isinstance(a, int) and isinstance(b, int):
        assert isinstance(c, int)
        assert c * b >= 0 # same sign or c == 0
    else:
        assert isinstance(c, float)
        assert sign(c) == sign(b)
    assert abs(c) < abs(b)
    assert math.isclose((a - c) / b, round((a - c) / b))

It’s a little hard to phrase this in a way that covers all possible sign and type combinations and accounts for floating-point imprecision, but I’m pretty confident in the above. One specific gotcha for floats is that, because of that floating-point imprecision, the result for a % b might sometimes appear to give b rather than 0. In fact, it simply gives a value very close to b, because the result of the division wasn’t quite exact:

>>> # On my version of Python
>>> 3.5 % 0.1
0.09999999999999981
>>> # On some other versions, it might appear as 0.1,
>>> # because of the internal rules for formatting floats for display

What if abs(a) < abs(b)?

A lot of people seem to think this is a special case, or for some reason have difficulty understanding what happens. But there is nothing special here.

For example: consider -1 % 3. How much, as a positive quantity (because 3 is positive), do we have to subtract from -1, in order to get a result divisible by 3? -1 is not divisible by 3; -1 - 1 is -2, which is also not divisible; but -1 - 2 is -3, which is divisible by 3 (dividing in exactly -1 times). By subtracting 2, we get back to divisibility; thus 2 is our predicted answer – and it checks out:

>>> -1 % 3
2

What about with b equal to zero?

It will raise ZeroDivisionError, regardless of whether b is integer zero, floating-point positive zero, or floating-point negative zero. In particular, it will not result in a NaN value.

What about special float values?

As one might expect, nan and signed infinity values for a produce a nan result, as long as b is not zero (which overrides everything else). nan values for b result in nan as well. NaN cannot be signed, so the sign of b is irrelevant in these cases.

Also as one might expect, inf % inf gives nan, regardless of the signs. If we are sharing out an infinite amount of as to an infinite amount of bs, there’s no way to say "which infinity is bigger" or by how much.

The only slightly confusing cases are when b is a signed infinity value:

>>> 0 % inf
0.0
>>> 0 % -inf
-0.0
>>> 1 % inf
1.0
>>> 1 % -inf
-inf

As always, the result takes the sign of b. 0 is divisible by anything (except NaN), including infinity. But nothing else divides evenly into infinity. If a has the same sign as b, the result is simply a (as a floating-point value); if the signs differ, it will be b. Why? Well, consider -1 % inf. There isn’t a finite value we can subtract from -1, in order to get to 0 (the unique value that we can divide into infinity). So we have to keep going, to infinity. The same logic applies to 1 % -inf, with all the signs reversed.

What about other types?

It’s up to the type. For example, the Decimal type overloads the operator so that the result takes the sign of the numerator, even though it functionally represents the same kind of value that a float does. And, of course, strings use it for something completely different.

Why not always give a positive result, or take the sign of a?

The behaviour is motivated by integer division. While % happens to work with floating-point numbers, it’s specifically designed to handle integer inputs, and the results for floats fall in line to be consistent with that.

After making the choice for a // b to give a floored division result, the % behaviour preserves a useful invariant:

>>> def check_consistency(a, b):
...     assert (a // b) * b + (a % b) == a
... 
>>> for a in range(-10, 11):
...     for b in range(-10, 11):
...         if b != 0:
...             check_consistency(a, b) # no assertion is raised
...

In other words: adding the modulus value back, corrects the error created by doing an integer division.

(This, of course, lets us go back to the first section, and say that a % b simply computes a - ((a // b) * b). But that just kicks the can down the road; we still need to explain what // is doing for signed values, especially for floats.)

One practical application for this is when converting pixel coordinates to tile coordinates. // tells us which tile contains the pixel coordinate, and then % tells us the offset within that tile. Say we have 16×16 tiles: then the tile with x-coordinate 0 contains pixels with x-coordinates 0..15 inclusive, tile 1 corresponds to pixel coordinate values 16..31, and so on. If the pixel coordinate is, say, 100, we can easily calculate that it is in tile 100 // 16 == 6, and offset 100 % 16 == 4 pixels from the left edge of that tile.

We don’t have to change anything in order to handle tiles on the other side of the origin. The tile at coordinate -1 needs to account for the next 16 pixel coordinates to the left of 0 – i.e., -16..-1 inclusive. And indeed, we find that e.g. -13 // 16 == -1 (so the coordinate is in that tile), and -13 % 16 == 3 (that’s how far it is from the left edge of the tile).

By setting the tile width to be positive, we defined that the within-tile coordinates progress left-to-right. Therefore, knowing that a point is within a specific tile, we always want a positive result for that offset calculation. Python’s % operator gives us that, on both sides of the y-axis.

What if I want it to work another way?

math.fmod will take the sign of the numerator. It will also return a floating-point result, even for two integer inputs, and raises an exception for signed-infinity a values with non-nan b values:

>>> math.fmod(-13, 16)
-13.0
>>> math.fmod(13, -16)
13.0
>>> math.fmod(1, -inf) # not -inf
1.0
>>> math.fmod(inf, 1.0) # not nan
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: math domain error

It otherwise handles special cases the same way – a zero value for b raises an exception; otherwise any nan present causes a nan result.

If this also doesn’t suit your needs, then carefully define the exact desired behaviour for every possible corner case, figure out where they differ from the built-in options, and make a wrapper function.