bitmath

library2.1.1pypypi✓ verified 86d ago

bitmath is a Python library (version 1.3.3.1) for representing, converting, and manipulating file sizes with different prefix notations (SI and NIST). It provides functionality for unit conversion (e.g., kB to GiB), arithmetic operations, rich comparisons, and human-readable formatting. The library's core functionality is stable and widely used for precise file size handling, though its release cadence has stalled.

data serialization

pip install bitmath

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BITMATH

bitmath

datapythonv2.1.1

Install

1.5s avg

Import

39ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.1 · 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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.041s · 17.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.037s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MiB

✓ from bitmath import MiB

KiB

✓ from bitmath import KiB

* (all units)

✓ from bitmath import *

parse_string

✓ import bitmath bitmath.parse_string(...)

getsize

✓ import bitmath bitmath.getsize(...)

Demonstrates how to instantiate bitmath objects, convert between units, perform basic arithmetic, and parse string representations of file sizes.

import bitmath # Instantiate some bitmath objects file_size_mib = bitmath.MiB(100) # 100 Mebibytes network_speed_mb = bitmath.MB(500) # 500 Megabytes # Convert units file_size_kib = file_size_mib.to_KiB() # Convert to Kibibytes print(f"100 MiB is {file_size_kib}") # Perform arithmetic total_data = file_size_mib + bitmath.GiB(2) print(f"100 MiB + 2 GiB = {total_data.best_prefix()}") # Parse a string parsed_size = bitmath.parse_string("1.5 TiB") print(f"Parsed size: {parsed_size}")

Debug

Known issues

gotchaThe `bitmath.format()` context manager is not thread-safe. Using it in a threaded environment may lead to unexpected results or errors. The suggested workaround is to apply formatting to each object instance directly using its `.format()` method.

fix

Avoid `bitmath.format()` in multi-threaded contexts; instead, use `instance.format()` directly on `bitmath` objects.

affects: All versions

gotcha`bitmath.parse_string()` is strict and will raise a `ValueError` for non-standard units (e.g., '4.7 G' instead of '4.7 GiB' or '4.7 GB') or non-string inputs. For more lenient parsing of non-standard units, `bitmath.parse_string_unsafe()` is available, but its usage requires careful consideration of potential ambiguities.

fix

Ensure input strings conform to standard SI or NIST unit notations (e.g., '100 MiB', '5 GB') when using `bitmath.parse_string()`. If parsing unknown formats, consider `bitmath.parse_string_unsafe()` and review its documentation.

affects: All versions

gotcha`bitmath.query_device_capacity()` requires superuser (root/admin) privileges to make system calls for reading device capacity. It is also only verified to work on Linux and macOS platforms.

fix

Run your application with appropriate administrative privileges when using `query_device_capacity()` on Linux/macOS. Be aware of platform limitations.

affects: All versions

gotchaWhen performing arithmetic operations between `bitmath` types and standard Python number types (integers or floats), the resulting type and behavior can sometimes be unexpected, particularly with bitwise operations. Results may not always align with intuitive unit conversions.

fix

Explicitly convert numbers to `bitmath` types before performing operations, or carefully review the documentation for mixed-type operation behaviors.

affects: All versions

Errors

Common errors & fixes

ValueError: Input cannot be parsed into a bitmath object.

Attempting to parse a string that does not match a recognized SI or NIST unit format (e.g., '100 MB' or '100 MiB') or providing a non-string input to `bitmath.parse_string()` will raise a ValueError.

fix

Ensure input strings for `bitmath.parse_string()` use standard unit suffixes (e.g., 'GB', 'GiB'). For parsing more flexible or unconventional formats, use `bitmath.parse_string_unsafe()`.

Installation fails or reports 'pip installs need pip >= 1.1.'

Historical versions of `bitmath` documentation noted a requirement for `pip` version 1.1 or newer. While modern `pip` versions far exceed this, users in very old or constrained Python environments might still encounter issues.

fix

Upgrade your `pip` installation to the latest version using `pip install --upgrade pip`. If a very old `pip` is unavoidable, a workaround historically suggested was to download the `bitmath` tarball from PyPI and install it manually: `pip install bitmath-x.y.z.tar.gz`.

Upgrade

Version history

2.1.1latest on PyPI · released May 25, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/timlnx/bitmath ↗

packagehttps://pypi.org/project/bitmath/ ↗

homepagehttps://bitmath.readthedocs.io/en/latest/index.html ↗