{"id":7044,"library":"bitmath","title":"bitmath","description":"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.","status":"maintenance","version":"1.3.3.1","language":"en","source_language":"en","source_url":"https://github.com/tbielawa/bitmath","tags":["file size","unit conversion","bytes","bits","mathematics","data conversion"],"install":[{"cmd":"pip install bitmath","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"symbol":"MiB","correct":"from bitmath import MiB"},{"symbol":"KiB","correct":"from bitmath import KiB"},{"symbol":"* (all units)","correct":"from bitmath import *"},{"symbol":"parse_string","correct":"import bitmath\nbitmath.parse_string(...)"},{"symbol":"getsize","correct":"import bitmath\nbitmath.getsize(...)"}],"quickstart":{"code":"import bitmath\n\n# Instantiate some bitmath objects\nfile_size_mib = bitmath.MiB(100) # 100 Mebibytes\nnetwork_speed_mb = bitmath.MB(500) # 500 Megabytes\n\n# Convert units\nfile_size_kib = file_size_mib.to_KiB() # Convert to Kibibytes\nprint(f\"100 MiB is {file_size_kib}\")\n\n# Perform arithmetic\ntotal_data = file_size_mib + bitmath.GiB(2)\nprint(f\"100 MiB + 2 GiB = {total_data.best_prefix()}\")\n\n# Parse a string\nparsed_size = bitmath.parse_string(\"1.5 TiB\")\nprint(f\"Parsed size: {parsed_size}\")","lang":"python","description":"Demonstrates how to instantiate bitmath objects, convert between units, perform basic arithmetic, and parse string representations of file sizes."},"warnings":[{"fix":"Avoid `bitmath.format()` in multi-threaded contexts; instead, use `instance.format()` directly on `bitmath` objects.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run your application with appropriate administrative privileges when using `query_device_capacity()` on Linux/macOS. Be aware of platform limitations.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly convert numbers to `bitmath` types before performing operations, or carefully review the documentation for mixed-type operation behaviors.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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()`.","cause":"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.","error":"ValueError: Input cannot be parsed into a bitmath object."},{"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`.","cause":"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.","error":"Installation fails or reports 'pip installs need pip >= 1.1.'"}]}