humanfriendly is a Python library that provides user-friendly output for text interfaces, including parsing and formatting numbers, file sizes, pathnames, and timespans. It also offers utilities for terminal interaction like text styling and prompting. The current version is 10.0, released in September 2021, with a release cadence that has included several minor and major updates in recent years and ongoing maintenance for Python compatibility on various platforms.
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.925 runs
installs and imports cleanly · install 0.0s · import 0.099s · 18.4MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.6s · import 0.091s · 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.)
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.