gmpy2: GMP/MPFR/MPC for Python

2.3.0 · active · verified Mon Apr 13

gmpy2 is an optimized, C-coded Python extension module that provides an interface to the GMP (GNU Multiple Precision Arithmetic Library), MPFR (Multiple-Precision Floating-point Reliable Library), and MPC (Multiple Precision Complex Library). It enables fast arbitrary-precision integer, rational, real, and complex arithmetic in Python. The current stable version is 2.3.0, and it is actively maintained with regular updates to support newer Python versions and fix bugs.

Warnings

breaking Future versions of gmpy2 (e.g., v2.4.0 and later) will drop support for CPython versions older than 3.11. Users currently on Python 3.9 or 3.10 with gmpy2 2.3.0 will need to upgrade their Python interpreter to at least 3.11 before upgrading to gmpy2 v2.4.0 (stable) or newer.
Fix: Upgrade Python to 3.11 or newer before updating gmpy2 past version 2.3.0.
gotcha Installation via `pip` usually provides pre-compiled binary wheels which include the necessary GMP, MPFR, and MPC C libraries. However, if a wheel is not available for your specific platform or Python version, `pip install gmpy2` will attempt to build from source, requiring these underlying C development libraries (e.g., `libgmp-dev`, `libmpfr-dev`, `libmpc-dev` on Debian/Ubuntu) to be pre-installed on your system.
Fix: Ensure GMP, MPFR, and MPC development libraries are installed on your system if pre-compiled wheels are not available.
gotcha Arbitrary-precision arithmetic can be computationally intensive and memory-hungry, especially with extremely large numbers or extensive operations. While `gmpy2` is highly optimized, unmanaged use can still lead to significant performance bottlenecks or memory exhaustion for very demanding computations.
Fix: Carefully manage the precision and scale of numbers. Monitor memory usage and CPU time for performance-critical sections. Consider using `xmpz` for mutable integer operations if appropriate.
gotcha The `gmpy2.context` object, which controls parameters like floating-point precision, rounding mode, and exception handling, is a global object by default. Directly modifying `gmpy2.get_context()` can cause side effects across different parts of an application.
Fix: For temporary or localized changes to context settings, use `with gmpy2.localcontext() as ctx:`, which creates a thread-local copy and restores the previous context upon exiting the `with` block. Alternatively, explicitly create and activate contexts with `gmpy2.set_context(new_context)` and `gmpy2.get_context().copy()`.
deprecated The `mpf` type, which was part of the original `gmpy` library (the predecessor to `gmpy2`), was renamed to `mpfr` in `gmpy2` version 2.0.0b1 to reflect its reliance on the MPFR library. Code migrating from older `gmpy` to `gmpy2` should update `mpf` references to `mpfr`.
Fix: Replace all instances of `gmpy.mpf` with `gmpy2.mpfr`.

Install

pip install gmpy2 Install stable release

Imports

mpz
```
from gmpy2 import mpz
```
mpq
```
from gmpy2 import mpq
```
mpfr
```
from gmpy2 import mpfr
```
mpc
```
from gmpy2 import mpc
```
get_context
```
from gmpy2 import get_context
```
*
```
from gmpy2 import mpz, mpfr
```
Importing all symbols with '*' is not recommended to avoid potential name conflicts with other modules or variables.

Quickstart

This quickstart demonstrates basic arbitrary-precision integer (mpz), real (mpfr), and rational (mpq) arithmetic. It also shows how to manage floating-point precision using `gmpy2.get_context()` and `gmpy2.localcontext()` to control precision settings. Constants should ideally be passed as strings to `mpfr` to ensure full arbitrary precision from the start, avoiding Python's native float limitations.

import gmpy2
from gmpy2 import mpz, mpfr, get_context

# Arbitrary-precision integer arithmetic
a = mpz(12345678901234567890 ** 2)
b = mpz(5)
print(f"mpz square: {a}")
print(f"mpz division: {a / b}")

# Arbitrary-precision floating-point real arithmetic
# Use strings for exact representation to avoid Python float precision issues
pi_approx = mpfr('3.14159265358979323846264338327950288')
print(f"Default precision pi: {pi_approx}")

# Manage precision using a context
current_context = get_context()
original_precision = current_context.precision

with gmpy2.localcontext() as ctx:
    ctx.precision = 100 # Set precision to 100 bits
    pi_high_prec = gmpy2.const_pi()
    print(f"High precision pi (100 bits): {pi_high_prec}")

print(f"Original precision after context block: {current_context.precision == original_precision}")

# Example with rational numbers
r = gmpy2.mpq(1, 3) + gmpy2.mpq(1, 4)
print(f"mpq sum: {r}")

view raw JSON →