isort Documentation

You can test isort's import sorting capabilities without installing it locally by using the live isort editor. This editor runs a complete Python 3 installation with isort inside your browser using Pyodide, ensuring that no code is transmitted to any server.

To use the live tester:

1. Paste your Python imports into the input editor.
2. Provide configuration settings in the configuration editor using JSON format.
3. View the formatted output in the output editor.

Use # isort: split to signal that the current sort section is finished. All subsequent imports will be placed in a new sort grouping. You can also use it inline to prevent imports from swapping positions with those above or below them.

import e
import f

# isort: split

import a
import b
import c
import d

# Inline usage example:
import c
import b  # isort: split
import a

Because isort creates an immutable configuration for each CLI instance, you should not run a single command across multiple independent projects. Instead, execute a separate isort command for each project to ensure the correct configuration is applied to each.

# RECOMMENDED: Run separately
isort project1
isort project2

# RECOMMENDED: Run per project subdirectories
isort project1/src project1/test
isort project2/src project2/test

# NOT RECOMMENDED: Do not mix projects in one command
isort project1 project2

You can prevent isort from touching specific parts of your code using comments:

• Single import: Add # isort:skip to the end of the import line.
• Multi-line import: Add # isort:skip inside the parentheses.
• Entire file: Add isort:skip_file to the module's docstring.

import module  # isort:skip

from xyz import (abc,  # isort:skip
                 yo,
                 hey)

""" my_module.py
    Best module ever

   isort:skip_file
"""
import b
import a

Place # isort: skip on the same line as an import statement to prevent isort from sorting that specific import. This causes isort to treat the line as regular code, pushing it below the import section.

import b
import a # isort: skip

You can use a custom-named configuration file by specifying the path with the --settings-path flag.

Important: When using custom config files, always place settings inside an [isort] section rather than a [settings] section to avoid conflicts with other tools that might use the same file.

isort 5.0.0 is a major release with breaking changes. Key changes include:

• Import Placement: By default, isort no longer moves imports to the top of the file to allow for side effects between imports. To restore the old behavior, use the --float-to-top CLI flag or float_to_top=true in your config.
• Config Loading: isort 5 no longer merges multiple configuration files. You must use exactly one configuration file per project. Config files are loaded relative to the file being sorted. To specify a manual location, use the --settings-path flag.
• Pre-commit: If using pre-commit, remove any seed-isort-config steps as they are unnecessary and can cause conflicts.

isort searches for configuration files by traversing up to 25 parent directories from the target file. It stops at the first suitable file it finds and does not merge multiple configuration files. The search is relative to the current directory if isort . is used, or relative to the first path passed if multiple paths are provided. isort will not leave a git or Mercurial repository (it stops at .git or .hg directories).

To see which configuration file is being used and what settings are applied, run: isort . --show-config

To use isort in your local development environment instead of the browser-based tester, install it using pip:

pip install isort