Install & Compatibility
Where this runs
tested against v0.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.055s · 18.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.049s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BloomFilter
✓ from probables import BloomFilter
CountMinSketch
✓ from probables import CountMinSketch
CuckooFilter
✓ from probables import CuckooFilter
QuotientFilter
✓ from probables import QuotientFilter
This quickstart demonstrates how to initialize a BloomFilter, add elements to it, and check for element membership. Bloom filters are used for approximate set membership testing, guaranteeing no false negatives but allowing for a configurable rate of false positives.
from probables import BloomFilter
# Initialize a Bloom filter for 100,000 elements with a 0.05 (5%) false positive rate
blm = BloomFilter(est_elements=100000, false_positive_rate=0.05)
# Add elements
blm.add('apple')
blm.add('banana')
blm.add('orange')
# Check for membership
print(f"Is 'apple' in the filter? {blm.check('apple')}")
print(f"Is 'grape' in the filter? {blm.check('grape')}")
# Demonstrate false positive possibility (very low with chosen parameters for this small example)
# In a real scenario, with many elements, a non-member might occasionally return True.
if blm.check('nonexistent_fruit'):
print("Warning: A false positive occurred for 'nonexistent_fruit'.")
Debug
Known issues
breakingAs of v0.7.0, comparing mismatched Bloom filters (e.g., different sizes or hash functions) will now raise a `SimilarityError` instead of returning `None` for comparison operations.fixEnsure that Bloom filters being compared are compatible (e.g., created with the same parameters) or handle the `SimilarityError` exception if comparison is attempted on mismatched filters.
affects: >=0.7.0
breakingPython 3.9 support was dropped in v0.7.0. Python 3.8 support was dropped in v0.6.2, and 3.6/3.7 support in v0.5.9. The library now requires Python >=3.10.fixUpgrade your Python environment to version 3.10 or newer to use the latest versions of pyprobables.
affects: >=0.6.2, >=0.7.0
gotchaFor better raw performance, especially with high data volumes, consider supplying an alternative hashing algorithm compiled in C, such as those from `mmh3` or `pyhash`.fixInstall a C-optimized hashing library (e.g., `pip install mmh3`) and pass its functions to the probabilistic data structure's constructor via the `hash_function` parameter.
affects: all
gotchaBloom filters and other probabilistic data structures have a predefined or desired false positive rate based on the estimated number of elements (`est_elements`) during initialization. If the actual number of elements added exceeds this estimate, the false positive rate will increase beyond the desired amount.fixCarefully estimate the maximum number of elements you expect to add and initialize the data structure with a sufficiently large `est_elements` parameter to maintain the desired false positive rate. Some filters, like `ExpandingBloomFilter`, can auto-expand but come with their own considerations.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyprobables'
The 'pyprobables' package has not been installed in the current Python environment.
fixpip install pyprobables
ModuleNotFoundError: No module named 'probables'
An attempt was made to import the library using its old package name 'probables' instead of the current 'pyprobables'.
fixReplace `import probables` or `from probables import ...` with `import pyprobables` or `from pyprobables import ...`.
TypeError: __init__() missing 2 required positional arguments: 'capacity' and 'error_rate'
The BloomFilter class (and similar probabilistic structures) requires 'capacity' (expected number of items) and 'error_rate' (desired false positive probability) arguments during instantiation.
fixInstantiate BloomFilter by providing the required 'capacity' and 'error_rate', for example: `bf = BloomFilter(capacity=1000, error_rate=0.01)`.
TypeError: unhashable type: 'list'
Probabilistic data structures like Bloom Filters require input keys to be hashable for their internal hashing operations. Lists and dictionaries are mutable and thus not hashable by default in Python.
fixConvert the unhashable object into a hashable type (e.g., a tuple for lists) before adding it, or hash it manually. Example: `bf.add(tuple(my_list))` or `bf.add(json.dumps(my_dict))`.
Upgrade
Version history
0.7.0latest on PyPI · released Feb 8, 2026
Audit
Dependencies
No dependency data recorded yet.