Install & Compatibility
Where this runs
tested against v10.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.95 runs
installs and imports cleanly · install 0.0s · import 0.082s · 18.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.086s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
format_size
✓ from humanfriendly import format_size
✗ import humanfriendly; humanfriendly.format_size(...)
While direct import from the top-level package works and is aliased for backwards compatibility, many functions are now preferred to be imported from their specific submodules (e.g., humanfriendly.text). However, 'format_size' is still a primary direct import example in documentation.
parse_size
✓ from humanfriendly import parse_size
✗ import humanfriendly; humanfriendly.parse_size(...)
Similar to `format_size`, this is a common direct import.
prompt_for_input
✓ from humanfriendly.prompts import prompt_for_input
✗ from humanfriendly import prompt_for_input
Many functions previously exposed directly from the top-level 'humanfriendly' package are now aliases to functions in submodules (e.g., 'humanfriendly.prompts'). Importing from the submodule is the modern, non-deprecated approach.
format_timespan
✓ from humanfriendly import format_timespan
Directly importable and a core utility.
This quickstart demonstrates the core functionality of parsing and formatting human-readable file sizes and timespans. It prompts the user for input and shows both decimal and binary size formatting. It also includes a comment on how to use the command-line demo feature.
import os
from humanfriendly import format_size, parse_size
from humanfriendly.prompts import prompt_for_input
# Example of parsing and formatting file sizes
user_input = prompt_for_input("Enter a human-readable file size (e.g., 16GB, 5MB): ")
num_bytes = parse_size(user_input)
print(f"Parsed bytes: {num_bytes}")
print(f"Formatted (decimal): {format_size(num_bytes)}")
print(f"Formatted (binary): {format_size(num_bytes, binary=True)}")
# Example of formatting a timespan
from humanfriendly import format_timespan
seconds = 3665 # 1 hour, 1 minute, 5 seconds
print(f"Formatted timespan: {format_timespan(seconds)}")
# To demonstrate CLI features like spinners (requires running in terminal):
# import subprocess
# subprocess.run(['humanfriendly', '--demo'])
Debug
Known issues
deprecatedMany functions previously available directly from the top-level `humanfriendly` package are now aliases to functions in submodules (e.g., `humanfriendly.prompts.prompt_for_input`). Accessing these aliases will trigger a `DeprecationWarning`.fixImport functions directly from their respective submodules (e.g., `from humanfriendly.prompts import prompt_for_input`). Refer to the API documentation for correct paths.
affects: 7.0+ (aliases introduced), 10.0 (explicitly noted deprecation)
breakingThe internal `time_units` data structure was changed. Although not formally part of the documented API, this constitutes a technically backwards incompatible change if users were directly importing or relying on this internal variable.fixAvoid direct reliance on internal data structures. Use documented functions for time-related operations (e.g., `format_timespan`, `parse_timespan`).
affects: 10.0
gotchaThe default behavior for `format_size()` and `parse_size()` changed from using binary multiples (base-2, e.g., KiB) to decimal multiples (base-10, e.g., KB) in an earlier major version. Users expecting binary representation by default may get unexpected results.fixExplicitly pass `binary=True` to `format_size()` and `parse_size()` if you require binary (base-2) multiples. For example: `format_size(num_bytes, binary=True)`.
affects: Older versions (change happened before 4.18, details in issue #4, PR #8, #9).
gotchaOn Windows, advanced terminal styling and ANSI escape sequence features (like colors and spinners) might not work correctly without the `colorama` package, especially on older Windows versions. While Windows 10+ has native support, `colorama` provides broader compatibility.fixInstall `colorama` as an optional dependency: `pip install colorama`. `humanfriendly` will detect and use it automatically.
affects: All versions on Windows (particularly older ones).
gotchaThe `prompt_for_input()` function, and other interactive prompt functions, will raise an `EOFError` if run in a non-interactive environment where standard input (stdin) is closed or redirected to an empty source. These functions expect user input from a terminal.fixEnsure the script is run in an interactive terminal. If the script must run non-interactively, avoid calling interactive prompt functions or provide input via redirection (e.g., `echo 'my input' | python script.py`).
affects: All versions
breaking`humanfriendly.prompts.prompt_for_input()` and other interactive prompt functions expect an interactive terminal. Running these functions in a non-interactive environment (e.g., CI/CD pipeline, redirected input, or when a TTY is not allocated) will result in an `EOFError` because no input can be read from `stdin`.fixEnsure the script is executed in an interactive terminal. If running in a non-interactive environment, avoid using interactive prompt functions or handle `EOFError` gracefully. For automated scripts, provide input via environment variables, command-line arguments, or configuration files instead of interactive prompts.
affects: All versions where `humanfriendly.prompts` module exists.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'humanfriendly'
The 'humanfriendly' package is not installed in the Python environment, or the environment where it's installed is not active.
fixInstall the package using pip: `pip install humanfriendly`
ImportError: cannot import name 'on_windows' from 'humanfriendly.compat'
This error often occurs when an Anaconda distribution of `humanfriendly` is used, which might be an older or differently compiled version missing the `on_windows` function in `humanfriendly.compat`.
fixRemove the current `humanfriendly` installation and reinstall it from the `conda-forge` channel: `conda remove humanfriendly` then `conda install -c conda-forge humanfriendly`.
ModuleNotFoundError: No module named 'readline'
When using interactive functions like `humanfriendly.prompts.prompt_for_confirmation()` on Windows, the underlying `readline` module (which is primarily for Unix-like systems) is required but not available.
fixOn Windows, `humanfriendly` often falls back to a simpler input mechanism if `readline` is not found, but if a specific setup tries to enforce it or if the fallback fails, you might need to ensure `colorama` is installed for better terminal compatibility: `pip install colorama`. For `prompt_for_confirmation` specifically, consider if an alternative input method or a platform-specific check is needed if `readline` is strictly required.
humanfriendly.exceptions.InvalidSize: Invalid size: 'invalid string'
The `humanfriendly.parse_size()` function received an input string that it could not interpret as a valid file size (e.g., 'invalid string', '5 Z').
fixEnsure the input string to `parse_size()` is in a recognized human-friendly format, such as '10 KB', '1.5 GB', '500 bytes', or simply '1024'. Example: `parse_size('1.5 GB')` ModuleNotFoundError: No module named 'humanfriendly.tables'
This error indicates an attempt to import a function, such as `format_pretty_table`, from `humanfriendly.tables`, but the `tables` submodule is not found or correctly exposed in the package structure.
fixThe correct way to import `format_pretty_table` is usually `from humanfriendly.tables import format_pretty_table`. If this still fails, ensure your `humanfriendly` installation is complete and not corrupted, and that you are using a version where `format_pretty_table` is indeed part of `humanfriendly.tables`. If `format_pretty_table` was moved or renamed in a newer version, consult the changelog for the correct import path. (For version 10.0, this import is generally valid.)
Upgrade
Version history
10.0latest on PyPI · released Sep 17, 2021
Audit
Dependencies
monotonicoptionalRequired for Python versions < 3.3 for consistent time measurement.
pyreadline | pyreadline3optionalProvides console input handling features specifically on Windows.
coloramaoptionalEnhances terminal styling features on older Windows systems that lack native ANSI escape sequence support. Used automatically if installed.