Install & Compatibility
Where this runs
tested against v2.9.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.428s · 40.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 1.182s · 46MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ufmt_paths
✓ from ufmt import ufmt_paths
High-level API for formatting multiple files or directories recursively.
ufmt_file
✓ from ufmt import ufmt_file
High-level API for formatting a single file.
This quickstart demonstrates how to use the `ufmt_file` API to programmatically format a Python file. It creates a temporary file, formats it with `ufmt`, prints the original and formatted content, and then cleans up the temporary file. For simple command-line usage, run `ufmt format <path>` in your terminal.
import os
from pathlib import Path
from ufmt import ufmt_file
from black import Mode, TargetVersion
from usort import Config
def main():
# Create a dummy Python file
dummy_content = (
"import os, sys\n\ndef my_func ( param1, param2 ) :\n \"\"\"A docstring.\"\"\"\n return param1 + param2\n"
)
dummy_file = Path("temp_module.py")
dummy_file.write_text(dummy_content)
print(f"Original content of {dummy_file.name}:\n---\n{dummy_content.strip()}\n---")
# Define black and usort configs (optional, ufmt can detect from pyproject.toml)
# For this example, we provide minimal configs
black_config = Mode(target_versions={TargetVersion.PY310})
usort_config = Config()
# Format the file using the ufmt API
result = ufmt_file(
path=dummy_file,
black_config=black_config,
usort_config=usort_config,
return_content=True
)
if result.error:
print(f"Error formatting {dummy_file.name}: {result.error}")
elif result.changed:
print(f"Formatted content of {dummy_file.name}:\n---\n{result.after.decode().strip()}\n---")
else:
print(f"{dummy_file.name} was already formatted correctly.\n---\n{result.after.decode().strip()}\n---")
# Clean up the dummy file
dummy_file.unlink()
if __name__ == "__main__":
main()
ufmt --version
Errors
Common errors & fixes
ufmt: command not found
The `ufmt` command-line tool is not found in your system's PATH, likely because it was not installed or the Python environment where it was installed is not active.
fixInstall `ufmt` using `pip install ufmt` or activate the virtual environment where it's already installed.
ERROR: ufmt requires Python >=3.10, but you are using Python 3.9.x
You are attempting to install or run `ufmt` with a Python version older than 3.10, which is its minimum requirement.
fixUpgrade your Python version to 3.10 or newer, or switch to a Python environment that meets the version requirement.
ModuleNotFoundError: No module named 'ufmt'
The `ufmt` library is not installed in the Python environment where the script is being executed, or the environment is not correctly activated.
fixInstall the library using `pip install ufmt` in the active Python environment.
Error: No such option: --some-black-option
You are attempting to use a command-line option that is not directly supported by `ufmt`, even if it's a valid option for `black` or `µsort`. `ufmt` handles configuration for these tools via `pyproject.toml`.
fixRemove the unsupported CLI option and instead configure `black` or `µsort` specific settings in your `pyproject.toml` file, which `ufmt` will automatically detect.
Upgrade
Version history
2.9.1latest on PyPI · released Feb 8, 2026
Audit
Dependencies
blackrequiredCore dependency for code formatting. It is highly recommended to pin its version for consistent CI results.
usortrequiredCore dependency for import sorting. It is highly recommended to pin its version for consistent CI results.