{"id":3311,"library":"usort","title":"µsort","description":"µsort (pronounced 'micro-sort') is a Python utility for safe, minimal import sorting. Its primary goal is to reorder imports within detected 'blocks' without making dangerous changes or altering other code formatting. It works by identifying distinct import blocks and applying sorting rules based on common Python conventions. The current version is 1.1.3, and it maintains a public changelog for releases.","status":"active","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/facebook/usort","tags":["import-sorting","formatter","code-quality","linter"],"install":[{"cmd":"pip install usort","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer to run.","package":"Python","optional":false}],"imports":[{"note":"Primary programmatic API for sorting a single file. For directory traversal, use `usort_path`.","symbol":"usort_file","correct":"import usort\nfrom pathlib import Path\n# ...\nusort.usort_file(path_obj, write=True)"}],"quickstart":{"code":"import usort\nfrom pathlib import Path\nimport tempfile\n\n# Create a dummy file with unsorted imports\ncode_to_sort = \"\"\"\nimport sys\nfrom os import path\nimport collections\n\"\"\"\n\n# Use a temporary file to demonstrate in-place sorting\nwith tempfile.NamedTemporaryFile(mode='w', suffix=\".py\", delete=False) as tmp_file:\n    tmp_file.write(code_to_sort)\n    tmp_file_path = Path(tmp_file.name)\n\ntry:\n    print(f\"Original file content:\\n---\\n{code_to_sort.strip()}\\n---\")\n    # Sort the file in-place\n    result = usort.usort_file(tmp_file_path, write=True)\n\n    if result.error:\n        print(f\"Error sorting file: {result.error}\")\n    else:\n        with open(tmp_file_path, 'r') as f:\n            sorted_code = f.read()\n        print(f\"Successfully sorted {tmp_file_path.name}\")\n        print(f\"Sorted file content:\\n---\\n{sorted_code.strip()}\\n---\")\nfinally:\n    tmp_file_path.unlink() # Clean up the temporary file","lang":"python","description":"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."},"warnings":[{"fix":"Use `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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `#usort:skip` or `#isort:skip` on the line of the import statement you wish to exclude from sorting or to force a block separation.","message":"To 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set 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.","message":"`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.","severity":"gotcha","affected_versions":"All versions (especially with Python 3.10+ syntax)"},{"fix":"Place your `usort` configurations (e.g., `known_first_party`, `known_third_party`) within the `[tool.usort]` section of your `pyproject.toml`.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}