Python math.nextafter() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Python 3.9+ / 3.12+

Definition

math.nextafter(x, y) returns the very next representable floating-point number after x moving toward y.

Added in Python 3.9 (with the optional steps= keyword argument added in Python 3.12), it moves one ULP at a time across IEEE 754 binary64 values—helpful for strict exclusive interval bounds and precision testing.

math.nextafter() is a function in Python's standard math module: import it with import math and call math.nextafter(...), or import the name directly with from math import nextafter. Added in Python 3.9; keyword-only steps parameter added in Python 3.12.

Syntax

Import math and pass start value x and target direction y (Python 3.9+).

python
import math

nxt = math.nextafter(x, y)
k_away = math.nextafter(x, y, steps=3)  # Python 3.12+
CallWhat it does
math.nextafter(1.0, 2.0)Returns 1.0000000000000002 (1.0 + 2**-52).
math.nextafter(1.0, 0.0)Returns 0.9999999999999999 (1.0 - 2**-53).
math.nextafter(0.0, -1.0)Returns -5e-324 (smallest negative subnormal).
math.nextafter(1.0, 1.0)Returns 1.0 (unchanged when equal).

Notice stepping upward from 1.0 moves twice as far (2**-52) as stepping downward from 1.0 (2**-53), because exponents change at exact powers of two. See math.ulp().

Function signatures
python
math.nextafter(x, y, /, *, steps=1)
# added in Python 3.9; keyword-only steps= added in Python 3.12

Parameters

ParameterDescription
xRequired positional starting real number.
yRequired positional direction target.
stepsOptional keyword-only non-negative integer count of steps (Python 3.12+). Default 1.

Return Value

Return ValueDescription
floatNext float after x toward y (or y if x == y; nan if either is NaN).

Python Examples

Example 1 — Inspect Asymmetric Float Neighbors Above and Below 1.0

Step up and down from 1.0 and from 0.0 toward negative numbers (Python 3.9+).

python
import math

up = math.nextafter(1.0, math.inf)
down = math.nextafter(1.0, -math.inf)
print("above 1.0:", up, up - 1.0)
print("below 1.0:", down, 1.0 - down)
print("below 0.0:", math.nextafter(0.0, -1.0))

How It Works

  1. Exponent boundary at 1.0. Values above 1.0 have spacing 2**-52 while values immediately below have spacing 2**-53—half as wide.
  2. Smallest negative subnormal. Stepping down from zero lands on -5e-324 (-2**-1074).
  3. Target infinity means direction. Passing math.inf or -math.inf cleanly picks up or down.

Example 2 — Take Three ULP Steps Portably Across Python 3.9 to 3.12+

Use steps=3 on Python 3.12+ or loop three calls on Python 3.9–3.11.

python
import math
import sys


def step_toward(x, y, count):
    if sys.version_info >= (3, 12):
        return math.nextafter(x, y, steps=count)
    cur = float(x)
    for _ in range(count):
        cur = math.nextafter(cur, y)
    return cur


res = step_toward(1.0, 2.0, 3)
print("3 steps above 1.0:", res)
print("gap in ULPs:", (res - 1.0) / math.ulp(1.0))

How It Works

  1. Version check for steps=. Python 3.12+ handles any step count in one C call; older 3.9–3.11 loop step by step.
  2. Exact 3-ULP shift. Dividing the difference by math.ulp(1.0) returns exact 3.0.
  3. Precision testing tool. Useful for checking rounding boundaries and strict open intervals.

Example 3 — Check Equal Inputs, Signed Zeros, and Stepping Down From Inf

See what nextafter() returns at x == y, (0.0, -0.0), and (inf, 0.0).

python
import math
import sys

print(math.nextafter(1.0, 1.0))
print(math.nextafter(0.0, -0.0))
max_finite = math.nextafter(math.inf, 0.0)
print(max_finite == sys.float_info.max)
print(math.isfinite(max_finite))

How It Works

  1. Equal targets stay equal. When x == y, nextafter returns y as a float (converting 0.0 toward -0.0 to -0.0).
  2. Largest finite float. Stepping one notch down from positive infinity lands exactly on sys.float_info.max (~1.797e308).
  3. Avoids redundant imports cleanly. Checking finiteness confirms stepping from infinity produces a finite float.

Frequently Asked Questions

Python 3.9 added math.nextafter(x, y), and Python 3.12 added the keyword-only steps= parameter.
Because 1.0 is a power of two (2**0), numbers just below 1.0 lie in exponent 2**-1 where bit spacing is half as large (2**-53 vs 2**-52).
-5e-324, the smallest magnitude negative subnormal float.
sys.float_info.max (1.7976931348623157e+308), the largest finite binary64 float.
math.ulp(x) gives the size of the gap at x, whereas math.nextafter(x, y) returns the actual neighboring float toward y.

Next: math.perm()

Return the number of ordered k-permutations from n items.

perm() →

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.

10 people found this page helpful