PyRoaring

1.0.4 verified Tue May 12 auth: no python install: verified

PyRoaring is a Python library providing an efficient and light-weight ordered set of integers. It serves as a Python wrapper for the highly optimized C library CRoaring, which implements Roaring Bitmaps. The library is actively maintained, with the current version being 1.0.4, and sees regular releases with new features and improvements.

pip install pyroaring

Common errors

error ModuleNotFoundError: No module named 'pyroaring' ↓

cause The 'pyroaring' package is not installed in the Python environment, or the environment where it's installed is not the one being used.

fix

Install the package using pip: pip install pyroaring

error AttributeError: module 'pyroaring' has no attribute 'BitMap' ↓

cause The 'BitMap' alias for 'RoaringBitmap' was deprecated in pyroaring version 0.5.0 and fully removed in version 0.6.0. Older code or tutorials might still reference it.

fix

Use 'RoaringBitmap' instead of 'BitMap'. For example: from pyroaring import RoaringBitmap

error TypeError: expected an integer ↓

cause Methods like 'add()', 'discard()', or 'update()' in pyroaring are designed to work exclusively with integer values, but a non-integer (e.g., float or string) was provided.

fix

Ensure that only integer values are passed to pyroaring methods that expect integer elements.

error Failed building wheel for pyroaring ↓

cause As a C extension, pyroaring requires a C compiler (like GCC or Clang) and Python development headers to build from source if a pre-built wheel is not available for your specific Python version and operating system.

fix

Install the necessary build tools for your operating system (e.g., sudo apt-get install build-essential python3-dev on Debian/Ubuntu, xcode-select --install on macOS, or Visual C++ Build Tools on Windows).

Warnings

breaking Python 3.7 support was dropped in PyRoaring 1.0.0, and Python 3.8 support was dropped in PyRoaring 1.0.4. Users on these older Python versions must use an earlier PyRoaring release. ↓

fix Upgrade to Python 3.9 or higher, or pin pyroaring to an earlier version (e.g., `<1.0.0` for Python 3.7, `<1.0.4` for Python 3.8).

breaking Prior to version 1.0.0, in-place operations where a BitMap was modified by itself (e.g., `bm &= bm`) were not correctly handled due to an underlying CRoaring library limitation. This was fixed in 1.0.0. ↓

fix Upgrade to PyRoaring 1.0.0 or later to ensure correct behavior for in-place self-operations. If upgrading is not possible, avoid such operations or create a copy before modifying.

gotcha When compiling PyRoaring from source, specific Cython version compatibility issues have been noted. Version 1.0.2 restricted Cython to `<3.1.0` due to a bug, although earlier 0.4.3 added general Cython 3 compatibility. Ensure your Cython version is compatible with the PyRoaring version you are compiling. ↓

fix If compiling from source, consult the PyRoaring release notes or `setup.py` for recommended Cython versions. For most users, installing pre-built wheels with `pip install pyroaring` avoids this issue.

gotcha Safe deserialization of bitmaps was introduced in PyRoaring 1.0.1. Earlier versions might be vulnerable to issues if deserializing untrusted or malformed data. ↓

fix Upgrade to PyRoaring 1.0.1 or later to benefit from safe deserialization, especially when handling data from external sources.

gotcha PyRoaring offers two main classes: `BitMap` for 32-bit integers (0 to 2**32-1) and `BitMap64` for 64-bit integers (0 to 2**64-1). Using `BitMap` for values exceeding 2**32-1 will lead to incorrect behavior or errors. ↓

fix Always use `from pyroaring import BitMap64` when working with integers that may exceed the 32-bit unsigned integer range.

Install

uv add pyroaring

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 26.7M

3.10 alpine (musl) - - 0.00s 26.4M

3.10 slim (glibc) wheel 1.6s 0.00s 26M

3.10 slim (glibc) - - 0.00s 25M

3.11 alpine (musl) wheel - 0.00s 28.6M

3.11 alpine (musl) - - 0.00s 28.4M

3.11 slim (glibc) wheel 1.8s 0.00s 28M

3.11 slim (glibc) - - 0.00s 28M

3.12 alpine (musl) wheel - 0.00s 20.5M

3.12 alpine (musl) - - 0.00s 20.3M

3.12 slim (glibc) wheel 1.6s 0.00s 20M

3.12 slim (glibc) - - 0.00s 19M

3.13 alpine (musl) wheel - 0.00s 20.2M

3.13 alpine (musl) - - 0.00s 19.9M

3.13 slim (glibc) wheel 1.5s 0.00s 19M

3.13 slim (glibc) - - 0.00s 19M

3.9 alpine (musl) wheel - 0.00s 26.1M

3.9 alpine (musl) - - 0.00s 25.9M

3.9 slim (glibc) wheel 2.0s 0.00s 25M

3.9 slim (glibc) - - 0.00s 25M

Imports

BitMap
```
from pyroaring import BitMap
```
BitMap64
```
from pyroaring import BitMap64
```
Use BitMap64 for integers larger than 2**32-1.

Quickstart last tested: 2026-04-24

This example demonstrates creating two Roaring BitMaps, adding elements, initializing from a list, performing intersection and union operations, and checking for element existence.

from pyroaring import BitMap

bm1 = BitMap()
bm1.add(3)
bm1.add(18)

bm2 = BitMap([3, 27, 42])

print(f"bm1 = {bm1}")
print(f"bm2 = {bm2}")
print(f"bm1 & bm2 = {bm1 & bm2}")
print(f"bm1 | bm2 = {bm1 | bm2}")
print(f"Does bm1 contain 3? {3 in bm1}")