Install & Compatibility
Where this runs
tested against v1.1.3 · 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.976s · 35.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.860s · 37MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
usort_file
✓ from usort import usort_file
✗ import usort
Config
✓ from usort import Config
Result
✓ from usort import Result
This example demonstrates how to use `usort` programmatically to sort imports in a Python file. It creates a temporary file with unsorted imports, applies `usort.usort_file` to sort it in-place, and then prints the sorted content.
import usort
from pathlib import Path
import tempfile
# Create a dummy file with unsorted imports
code_to_sort = """
import sys
from os import path
import collections
"""
# Use a temporary file to demonstrate in-place sorting
with tempfile.NamedTemporaryFile(mode='w', suffix=".py", delete=False) as tmp_file:
tmp_file.write(code_to_sort)
tmp_file_path = Path(tmp_file.name)
try:
print(f"Original file content:\n---\n{code_to_sort.strip()}\n---")
# Sort the file in-place
result = usort.usort_file(tmp_file_path, write=True)
if result.error:
print(f"Error sorting file: {result.error}")
else:
with open(tmp_file_path, 'r') as f:
sorted_code = f.read()
print(f"Successfully sorted {tmp_file_path.name}")
print(f"Sorted file content:\n---\n{sorted_code.strip()}\n---")
finally:
tmp_file_path.unlink() # Clean up the temporary file
usort --version
Debug
Known issues
gotchaWhen using `usort format <path>` from the command line or `usort_file(..., write=True)` programmatically, `usort` modifies files in-place. Always ensure you have version control or backups if experimenting.fixUse `usort diff <path>` to see changes without writing, or `usort check <path>` for CI validation. For programmatic use, omit `write=True` to get the sorted content without modifying the file.
affects: All versions
gotchaTo exclude specific imports from sorting or to act as block separators, use `comment markers` like `#usort:skip` or `#isort:skip` (for `isort` compatibility). Without these, `usort` will attempt to sort imports it deems safe within their blocks.fixAdd `#usort:skip` or `#isort:skip` on the line of the import statement you wish to exclude from sorting or to force a block separation.
affects: All versions
gotcha`usort` relies on `LibCST` for parsing. For files containing Python 3.10+ specific syntax (like `match` statements), you might need to explicitly enable `LibCST`'s native PEG parser.fixSet the environment variable `LIBCST_PARSER_TYPE="native"` before running `usort`, or call `usort.lib.native_parser.enable_native_parser()` in your code before parsing files.
affects: All versions (especially with Python 3.10+ syntax)
gotchaThe preferred method for configuring `usort` is via a `pyproject.toml` file, under the `[tool.usort]` table. `usort` will look for the nearest `pyproject.toml` upwards from the file being sorted.fixPlace your `usort` configurations (e.g., `known_first_party`, `known_third_party`) within the `[tool.usort]` section of your `pyproject.toml`.
affects: All versions
Upgrade
Version history
1.1.3latest on PyPI · released Jan 13, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.10 or newer to run.