Python math.remainder() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Python 3.7+

Definition

math.remainder(x, y) returns the IEEE 754 remainder x - n * y, where n is the integer closest to x / y.

If x / y lies exactly halfway between two integers, n is rounded to the even integer—so math.remainder(8, 3) returns -1.0 and math.remainder(3.0, 2.0) returns -1.0. The result always stays within [-|y|/2, +|y|/2].

math.remainder() is a function in Python's standard math module: import it with import math and call math.remainder(...), or import the name directly with from math import remainder. Added in Python 3.7.

Syntax

Import math and pass dividend x and nonzero divisor y.

python
import math

delta = math.remainder(x, y)
CallWhat it does
math.remainder(7, 3)Returns 1.0 (nearest multiple is 6 = 2 * 3).
math.remainder(8, 3)Returns -1.0 (nearest multiple is 9 = 3 * 3).
math.remainder(3.0, 2.0)Returns -1.0 (1.5 ties to even 2).
math.remainder(5.0, 0.0)Raises ValueError: divisor cannot be zero.

Added in Python 3.7. Unlike math.fmod() or %, remainder() can be negative even when both inputs are positive.

Function signatures
python
math.remainder(x, y, /)
# added in Python 3.7; exact IEEE 754 x - round_even(x / y) * y

Parameters

ParameterDescription
xRequired positional finite dividend (int or float).
yRequired positional nonzero divisor (int or float).

Return Value

Return ValueDescription
floatSigned distance from x to the nearest integer multiple of y.

Python Examples

Example 1 — Find Signed Offsets to the Nearest Grid Step

Measure how far numbers sit from the nearest multiple of 3.0 using math.remainder().

python
import math

for pos in [2.2, 7.0, 8.0, 10.6]:
    offset = math.remainder(pos, 3.0)
    nearest = pos - offset
    print(f"{pos:>4.1f} -> offset={offset:+5.1f} nearest={nearest:>4.1f}")

How It Works

  1. Center-balanced error. Position 2.2 is only 0.8 units below 3.0, so remainder() reports -0.8.
  2. Nearest multiple recovered. Subtracting the remainder from pos snaps cleanly to 3.0, 6.0, 9.0, and 12.0.
  3. Bound within half step. Every offset has magnitude at most 1.5.

Example 2 — Inspect IEEE Half-to-Even Ties at Exact Midpoints

Divide odd integers by 2.0 to watch exact .5 quotients round to even integers.

python
import math

for num in [1.0, 3.0, 5.0, 7.0]:
    rem = math.remainder(num, 2.0)
    print(f"remainder({num}, 2.0) = {rem:+4.1f}")

How It Works

  1. Midpoint 0.5 goes to 0. Zero is even, leaving remainder +1.0.
  2. Midpoint 1.5 goes to 2. Rounding up to even two subtracts four from three, returning -1.0.
  3. Alternating pattern. Every subsequent half-quotient alternates between rounding down and up toward the even integer.

Example 3 — Wrap Any Bearing Into [-180, 180] and Catch Zero Divisor

Center angles cleanly around zero degrees and handle zero divisors safely.

python
import math

print(math.remainder(270.0, 360.0))
print(math.remainder(-270.0, 360.0))

try:
    math.remainder(5.0, 0.0)
except ValueError:
    print("remainder divisor cannot be zero")

How It Works

  1. Minimal signed turn. Rotating 270.0 degrees is equivalent to turning -90.0 degrees the shorter way around.
  2. Reversed sign works cleanly. Negative -270.0 lands at +90.0.
  3. Zero divisor error. Passing 0.0 raises ValueError.

Frequently Asked Questions

math.remainder() was added in Python 3.7.
Because 8 / 3 is 2.66..., whose nearest integer is 3, so 8 - 3 * 3 equals -1.0.
It rounds the quotient to the nearest even integer (banker's rounding), so remainder(3.0, 2.0) is -1.0 while remainder(5.0, 2.0) is +1.0.
fmod() truncates the quotient toward zero and keeps the sign of x; remainder() rounds the quotient to nearest even and stays within [-|y|/2, +|y|/2].
ValueError, matching math.fmod().

Next: math.signbit()

Return True if the IEEE 754 sign bit of x is set.

signbit() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

15 people found this page helpful