isort Documentation

File: README.md Copy Chapter

Read Latest Documentation - Browse GitHub Code Repository

isort your imports, so you don't have to.

isort is a Python utility / library to sort imports alphabetically and
automatically separate into sections and by type. It provides a command line
utility, Python library and plugins for various
editors to
quickly sort all your imports. It requires Python 3.10+ to run but
supports formatting Python 2 code too.

• Try isort now from your browser!
• Using black? See the isort and black compatibility guide.
• isort has official support for pre-commit!

Before isort:

from my_lib import Object

import os

from my_lib import Object3

from my_lib import Object2

import sys

from third_party import lib15, lib1, lib2, lib3, lib4, lib5, lib6, lib7, lib8, lib9, lib10, lib11, lib12, lib13, lib14

import sys

from __future__ import absolute_import

from third_party import lib3

print("Hey")
print("yo")

After isort:

from __future__ import absolute_import

import os
import sys

from third_party import (lib1, lib2, lib3, lib4, lib5, lib6, lib7, lib8,
                         lib9, lib10, lib11, lib12, lib13, lib14, lib15)

from my_lib import Object, Object2, Object3

print("Hey")
print("yo")

Installing isort Copy Chapter

Installing isort is as simple as:

pip install isort

Using isort Copy Chapter

From the command line:

To run on specific files:

isort mypythonfile.py mypythonfile2.py

To apply recursively:

isort .

If globstar
is enabled, isort . is equivalent to:

isort **/*.py

To view proposed changes without applying them:

isort mypythonfile.py --diff

Finally, to atomically run isort against a project, only applying
changes if they don't introduce syntax errors:

isort --atomic .

(Note: this is disabled by default, as it prevents isort from
running against code written using a different version of Python.)

From within Python:

import isort

isort.file("pythonfile.py")

or:

import isort

sorted_code = isort.code("import b\nimport a\n")

Installing isort's for your preferred text editor Copy Chapter

Several plugins have been written that enable to use isort from within a
variety of text-editors. You can find a full list of them on the isort
wiki.
Additionally, I will enthusiastically accept pull requests that include
plugins for other text editors and add documentation for them as I am
notified.

Multi line output modes Copy Chapter

You will notice above the "multi_line_output" setting. This setting
defines how from imports wrap when they extend past the line_length
limit and has 12 possible settings.

Indentation Copy Chapter

To change the how constant indents appear - simply change the
indent property with the following accepted formats:

• Number of spaces you would like. For example: 4 would cause standard
  4 space indentation.
• Tab
• A verbatim string with quotes around it.

For example:

"    "

is equivalent to 4.

For the import styles that use parentheses, you can control whether or
not to include a trailing comma after the last import with the
include_trailing_comma option (defaults to False).

Intelligently Balanced Multi-line Imports Copy Chapter

As of isort 3.1.0 support for balanced multi-line imports has been
added. With this enabled isort will dynamically change the import length
to the one that produces the most balanced grid, while staying below the
maximum import length defined.

Example:

from __future__ import (absolute_import, division,
                        print_function, unicode_literals)

Will be produced instead of:

from __future__ import (absolute_import, division, print_function,
                        unicode_literals)

To enable this set balanced_wrapping to True in your config or pass
the -e option into the command line utility.

Custom Sections and Ordering Copy Chapter

isort provides configuration options to change almost every aspect of how
imports are organized, ordered, or grouped together in sections.

Click here for an overview of all these options.

Skip processing of imports (outside of configuration) Copy Chapter

To make isort ignore a single import simply add a comment at the end of
the import line containing the text isort:skip:

import module  # isort:skip

or:

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

To make isort skip an entire file simply add isort:skip_file to the
module's doc string:

""" my_module.py
    Best module ever

   isort:skip_file
"""

import b
import a

Adding or removing an import from multiple files Copy Chapter

isort can be ran or configured to add / remove imports automatically.

See a complete guide here.

Using isort to verify code Copy Chapter

The `--check-only` option Copy Chapter

isort can also be used to verify that code is correctly formatted
by running it with -c. Any files that contain incorrectly sorted
and/or formatted imports will be outputted to stderr.

isort **/*.py -c -v

SUCCESS: /home/timothy/Projects/Open_Source/isort/isort_kate_plugin.py Everything Looks Good!
ERROR: /home/timothy/Projects/Open_Source/isort/isort/isort.py Imports are incorrectly sorted.

One great place this can be used is with a pre-commit git hook, such as
this one by @acdha:

https://gist.github.com/acdha/8717683

This can help to ensure a certain level of code quality throughout a
project.

Git hook Copy Chapter

isort provides a hook function that can be integrated into your Git
pre-commit script to check Python code before committing.

More info here.

Spread the word Copy Chapter

Place this badge at the top of your repository to let others know your project uses isort.

For README.md:

[](https://isort.readthedocs.io/)

Or README.rst:

.. image:: https://img.shields.io/badge/imports-isort-%231674b1?style=flat&labelColor=ef8336
    :target: https://isort.readthedocs.io/

Security contact information Copy Chapter

To report a security vulnerability, please use the Tidelift security
contact. Tidelift will coordinate the
fix and disclosure.

Why isort? Copy Chapter

isort simply stands for import sort. It was originally called
"sortImports" however I got tired of typing the extra characters and
came to the realization camelCase is not pythonic.

I wrote isort because in an organization I used to work in the manager
came in one day and decided all code must have alphabetically sorted
imports. The code base was huge - and he meant for us to do it by hand.
However, being a programmer - I'm too lazy to spend 8 hours mindlessly
performing a function, but not too lazy to spend 16 hours automating it.
I was given permission to open source sortImports and here we are :)

Get professionally supported isort with the Tidelift
Subscription

Professional support for isort is available as part of the Tidelift
Subscription.
Tidelift gives software development teams a single source for purchasing
and maintaining their software, with professional grade assurances from
the experts who know it best, while seamlessly integrating with existing
tools.

Thanks and I hope you find isort useful!

~Timothy Crosley

File: docs/configuration/action_comments.md Copy Chapter

Action comments

The most basic way to configure the flow of isort within a single file is action comments. These comments are picked up and interpreted by the isort parser during parsing.

isort: skip_file Copy Chapter

Tells isort to skip the entire file.

Example:

# !/bin/python3
# isort: skip_file
import os
import sys

...

!!! warning
This should be placed as high in the file as reasonably possible.
Since isort uses a streaming architecture, it may have already completed some work before it reaches the comment. Usually, this is okay - but can be confusing if --diff or any interactive options are used from the command line.

isort: skip Copy Chapter

If placed on the same line as (or within the continuation of a) an import statement, isort will not sort this import.
More specifically, it prevents the import statement from being recognized by isort as an import. In consequence, this line will be treated as code and be pushed down to below the import section of the file.

Example:

import b
import a # isort: skip <- this will now stay below b

!!! note
It is recommended to where possible use # isort: off and # isort: on or # isort: split instead as the behavior is more explicit and predictable.

isort: off Copy Chapter

Turns isort parsing off. Every line after an # isort: off statement will be passed along unchanged until an # isort: on comment or the end of the file.

Example:

import e
import f

# isort: off

import b
import a

isort: on Copy Chapter

Turns isort parsing back on. This only makes sense if an # isort: off comment exists higher in the file! This allows you to have blocks of unsorted imports, around otherwise sorted ones.

Example:

import e
import f

# isort: off

import b
import a

# isort: on

import c
import d

isort: split Copy Chapter

Tells isort the current sort section is finished, and all future imports belong to a new sort grouping.

Example:

import e
import f

# isort: split

import a
import b
import c
import d

You can also use it inline to keep an import from having imports above or below it swap position:

import c
import b  # isort: split
import a

!!! tip
isort split is exactly the same as placing an # isort: on immediately below an # isort: off

isort: dont-add-imports Copy Chapter

Tells isort to not automatically add imports to this file, even if --add-imports is set.

isort: dont-add-import: [IMPORT_LINE] Copy Chapter

Tells isort to not automatically add a particular import, even if --add-imports says to add it.

File: docs/configuration/add_or_remove_imports.md Copy Chapter

Add or remove imports

Adding an import to multiple files Copy Chapter

isort makes it easy to add an import statement across multiple files,
while being assured it's correctly placed.

To add an import to all files:

isort -a "from __future__ import print_function" *.py

To add an import only to files that already have imports:

isort -a "from __future__ import print_function" --append-only *.py

Removing an import from multiple files Copy Chapter

isort also makes it easy to remove an import from multiple files,
without having to be concerned with how it was originally formatted.

From the command line:

isort --rm "os.system" *.py

File: docs/configuration/black_compatibility.md Copy Chapter

Compatibility with black

Compatibility with black is very important to the isort project and comes baked in starting with version 5.
All that's required to use isort alongside black is to set the isort profile to "black".

!!! tip
Beyond the profile, it is common to set skip_gitignore (which is not enabled by default for isort as it requires git to be installed) and line_length as it is common to deviate from black's default of 88.

Using a config file (such as .isort.cfg) Copy Chapter

For projects that officially use both isort and black, we recommend setting the black profile in a config file at the root of your project's repository.
That way it's independent of how users call isort (pre-commit, CLI, or editor integration) the black profile will automatically be applied.

For instance, your pyproject.toml file would look something like

[tool.isort]
profile = "black"

Read More about supported config files.

CLI Copy Chapter

To use the profile option when calling isort directly from the commandline simply add the --profile black argument: isort --profile black.

A demo of how this would look like in your .travis.yml

language: python
python:
  - "3.10"

install:
  - pip install -r requirements-dev.txt
  - pip install isort black
  - pip install coveralls
script:
  - pytest my-package
  - isort --profile black my-package
  - black --check --diff my-package
after_success:
  - coveralls

See built-in profiles for more profiles.

Integration with pre-commit Copy Chapter

You can also set the profile directly when integrating isort within pre-commit.

- repo: https://github.com/pycqa/isort
    rev: 6.0.1
    hooks:
      - id: isort
        args: ["--profile", "black", "--filter-files"]

File: docs/configuration/config_files.md Copy Chapter

Supported config files

isort supports various standard config formats to allow customizations to be integrated into any project quickly.
When applying configurations, isort looks for the closest supported config file, in the order files are listed below.
You can manually specify the settings file or path by setting --settings-path from the command-line. Otherwise, isort will
traverse up to 25 parent directories until it finds a suitable config file.
Note that isort will not leave a git or Mercurial repository (checking for a .git or .hg directory).
As soon as it finds a file, it stops looking. The config file search is done relative to the current directory if isort .
or a file stream is passed in, or relative to the first path passed in if multiple paths are passed in.
isort never merges config files together due to the confusion it can cause.

!!! tip
You can always introspect the configuration settings isort determined, and find out which config file it picked up, by running isort . --show-config

.isort.cfg **[preferred format]** Copy Chapter

The first place isort will look for settings is in dedicated .isort.cfg files.
The advantage of using this kind of config file, is that it is explicitly for isort and follows a well understood format.
The downside, is that it means one more config file in your project when you may already have several polluting your file hierarchy.

An example a config from the isort project itself:

[settings]
profile=hug
src_paths=isort,test

pyproject.toml **[preferred format]** Copy Chapter

The second place isort will look, and an equally excellent choice to place your configuration, is within a pyproject.toml file.
The advantage of using this config file, is that it is quickly becoming a standard place to configure all Python tools.
This means other developers will know to look here and you will keep your projects root nice and tidy.
The only disadvantage is that other tools you use might not yet support this format, negating the cleanliness.

[tool.isort]
profile = "hug"
src_paths = ["isort", "test"]

setup.cfg Copy Chapter

setup.cfg can be thought of as the precursor to pyproject.toml. While isort and newer tools are increasingly moving to pyproject.toml, if you rely on many tools that
use this standard it can be a natural fit to put your isort config there as well.

[isort]
profile=hug
src_paths=isort,test

tox.ini Copy Chapter

tox is a tool commonly used in the Python community to specify multiple testing environments.
Because isort verification is commonly ran as a testing step, some prefer to place the isort config inside of the tox.ini file.

[isort]
profile = black
multi_line_output = 3

.editorconfig Copy Chapter

Finally, isort will look for a .editorconfig configuration with settings for Python source files. EditorConfig is a project to enable specifying a configuration for text editing behaviour once, allowing multiple command line tools and text editors to pick it up. Since isort cares about a lot of the same settings as a text-editor (like line-length) it makes sense for it to look within these files
as well.

root = true

[*.py]
profile = hug
indent_style = space
indent_size = 4
skip = build,.tox,venv
src_paths=isort,test

Custom config files Copy Chapter

Optionally, you can also create a config file with a custom name, or directly point isort to a config file that falls lower in the priority order, by using --settings-file.
This can be useful, for instance, if you want to have one configuration for .py files and another for .pyx - while keeping the config files at the root of your repository.

!!! tip
Custom config files should place their configuration options inside an [isort] section and never a generic [settings] section. This is because isort can't know for sure
how other tools are utilizing the config file.

Supporting multiple config files in single isort run Copy Chapter

If you have a directory structure where different sub-directories may have their separate configuration settings and you want isort to respect these configurations, not just apply the same global configuration for the entire directory then you can do so with the --resolve-all-configs flag. Using the --resolve-all-configs along with providing the directory root as --config-root argument(if the config-root is not explicitly defined, then isort will consider the current directory . where the shell is running), isort will traverse and parse all the config files defined under the --config-root and dynamically decide what configurations should be applied to a specific file by choosing the nearest config file in the file's path. For instance, if your directory structure is

directory_root

    subdir1
        .isort.cfg
        file1.py

    subdir2
        pyproject.toml
        file2.py

    subdir3
        file3.py

    setup.cfg

isort will sort subdir1/file1 according to the configurations defined in subdir1/.isort.cfg, subdir2/file2 with configurations from subdir2/pyproject.toml and subdir3/file3.py based on the setup.cfg settings.

!!! tip
You can always confirm exactly what config file was used for a file by running isort with the --verbose flag.

File: docs/configuration/custom_sections_and_ordering.md Copy Chapter

Custom sections and ordering

isort provides lots of features to enable configuring how it sections imports
and how it sorts imports within those sections.
You can change the section order with sections option from the default
of:

FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,LOCALFOLDER

to your preference (if defined, omitting a default section may cause errors):

sections=FUTURE,STDLIB,FIRSTPARTY,THIRDPARTY,LOCALFOLDER

You also can define your own sections and their order.

Example:

known_django=django
known_pandas=pandas,numpy
sections=FUTURE,STDLIB,DJANGO,THIRDPARTY,PANDAS,FIRSTPARTY,LOCALFOLDER

would create two new sections with the specified known modules.

The no_lines_before option will prevent the listed sections from being
split from the previous section by an empty line.

Example:

sections=FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
no_lines_before=LOCALFOLDER

would produce a section with both FIRSTPARTY and LOCALFOLDER modules
combined.

IMPORTANT NOTE: It is very important to know when setting known sections that the naming
does not directly map for historical reasons. For custom settings, the only difference is
capitalization (known_custom=custom VS sections=CUSTOM,...) for all others reference the
following mapping:

• known_standard_library : STANDARD_LIBRARY
• extra_standard_library : STANDARD_LIBRARY # Like known standard library but appends instead of replacing
• known_future_library : FUTURE
• known_first_party: FIRSTPARTY
• known_third_party: THIRDPARTY
• known_local_folder: LOCALFOLDER

This will likely be changed in isort 6.0.0+ in a backwards compatible way.

Auto-comment import sections Copy Chapter

Some projects prefer to have import sections uniquely titled to aid in
identifying the sections quickly when visually scanning. isort can
automate this as well. To do this simply set the
import_heading_{section_name} setting for each section you wish to
have auto commented - to the desired comment.

For Example:

import_heading_stdlib=Standard Library
import_heading_firstparty=My Stuff

Would lead to output looking like the following:

# Standard Library
import os
import sys

import django.settings

# My Stuff
import myproject.test

Ordering by import length Copy Chapter

isort also makes it easy to sort your imports by length, simply by
setting the length_sort option to True. This will result in the
following output style:

from evn.util import (
    Pool,
    Dict,
    Options,
    Constant,
    DecayDict,
    UnexpectedCodePath,
)

It is also possible to opt-in to sorting imports by length for only
specific sections by using length_sort_ followed by the section name
as a configuration item, e.g.:

length_sort_stdlib=1

Controlling how isort sections `from` imports Copy Chapter

By default isort places straight (import y) imports above from imports (from x import y):

import b
from a import a  # This will always appear below because it is a from import.

However, if you prefer to keep strict alphabetical sorting you can set force sort within sections to true. Resulting in:

from a import a  # This will now appear at top because a appears in the alphabet before b
import b

You can even tell isort to always place from imports on top, instead of the default of placing them on bottom, using from first.

from b import b # If from first is set to True, all from imports will be placed before non-from imports.
import a

File: docs/configuration/git_hook.md Copy Chapter

Git hook

isort provides a hook function that can be integrated into your Git
pre-commit script to check Python code before committing.

To cause the commit to fail if there are isort errors (strict mode),
include the following in .git/hooks/pre-commit:

#!/usr/bin/env python
import sys
from isort.hooks import git_hook

sys.exit(git_hook(strict=True, modify=True, lazy=True, settings_file=""))

If you just want to display warnings, but allow the commit to happen
anyway, call git_hook without the strict parameter. If you want to
display warnings, but not also fix the code, call git_hook without the
modify parameter.
The lazy argument is to support users who are "lazy" to add files
individually to the index and tend to use git commit -a instead.
Set it to True to ensure all tracked files are properly isorted,
leave it out or set it to False to check only files added to your
index.

If you want to use a specific configuration file for the hook, you can pass its
path to settings_file. If no path is specifically requested, git_hook will
search for the configuration file starting at the directory containing the first
staged file, as per git diff-index ordering, and going upward in the directory
structure until a valid configuration file is found or
MAX_CONFIG_SEARCH_DEPTH directories are checked. Check the source code for the
current value of this variable.
The settings_file parameter is used to support users who keep their configuration
file in a directory that might not be a parent of all the other files.

File: docs/configuration/github_action.md Copy Chapter

Github action

isort provides an official Github Action that can be used as part of a CI/CD workflow to ensure a project's imports are properly sorted.
The action can be found on the Github Actions Marketplace.

Usage Copy Chapter

The python-isort plugin is designed to be run in combination with the checkout and setup-python actions.
By default, it will run recursively from the root of the repository being linted and will exit with an error if the code is not properly sorted.

Inputs Copy Section

`isort-version`

Optional. Version of isort to use. Defaults to latest version of isort.

`sort-paths`

Optional. List of paths to sort, relative to your project root. Defaults to .

`configuration`

Optional. isort configuration options to pass to the isort CLI. Defaults to --check-only --diff.

`requirements-files`

Optional. Paths to python requirements files to install before running isort.
If multiple requirements files are provided, they should be separated by a space.
If custom package installation is required, dependencies should be installed in a separate step before using this action.

!!! tip
It is important that the project's dependencies be installed before running isort so that third-party libraries are properly sorted.

Outputs Copy Section

`isort-result`

Output of the isort CLI.

Example usage Copy Section

name: Run isort
on:
  - push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: 3.13
      - uses: isort/isort-action@v1
        with:
            requirementsFiles: "requirements.txt requirements-test.txt"

File: docs/configuration/multi_line_output_modes.md Copy Chapter

Multi line output modes

This config option defines how from imports wrap when they extend past the line_length
limit and has 12 possible settings:

0 - Grid Copy Chapter

from third_party import (lib1, lib2, lib3,
                         lib4, lib5, ...)

1 - Vertical Copy Chapter

from third_party import (lib1,
                         lib2,
                         lib3
                         lib4,
                         lib5,
                         ...)

2 - Hanging Indent Copy Chapter

from third_party import \
    lib1, lib2, lib3, \
    lib4, lib5, lib6

3 - Vertical Hanging Indent Copy Chapter

from third_party import (
    lib1,
    lib2,
    lib3,
    lib4
)

4 - Hanging Grid Copy Chapter

from third_party import (
    lib1, lib2, lib3, lib4,
    lib5, ...)

5 - Hanging Grid Grouped Copy Chapter

from third_party import (
    lib1, lib2, lib3, lib4,
    lib5, ...
)

6 - Hanging Grid Grouped Copy Chapter

Same as Mode 5. Deprecated.

7 - NOQA Copy Chapter

from third_party import lib1, lib2, lib3, ...  # NOQA

Alternatively, you can set force_single_line to True (-sl on the
command line) and every import will appear on its own line:

from third_party import lib1
from third_party import lib2
from third_party import lib3
...

8 - Vertical Hanging Indent Bracket Copy Chapter

Same as Mode 3 - Vertical Hanging Indent but the closing parentheses
on the last line is indented.

from third_party import (
    lib1,
    lib2,
    lib3,
    lib4,
    )

9 - Vertical Prefix From Module Import Copy Chapter

Starts a new line with the same from MODULE import prefix when lines are longer than the line length limit.

from third_party import lib1, lib2, lib3
from third_party import lib4, lib5, lib6

10 - Hanging Indent With Parentheses Copy Chapter

Same as Mode 2 - Hanging Indent but uses parentheses instead of backslash
for wrapping long lines.

from third_party import (
    lib1, lib2, lib3,
    lib4, lib5, lib6)

11 - Backslash Grid Copy Chapter

Same as Mode 0 - Grid but uses backslashes instead of parentheses to group imports.

from third_party import lib1, lib2, lib3, \
                        lib4, lib5

File: docs/configuration/options.md Copy Chapter

Configuration options for isort

As a code formatter isort has opinions. However, it also allows you to have your own. If your opinions disagree with those of isort,
isort will disagree but commit to your way of formatting. To enable this, isort exposes a plethora of options to specify
how you want your imports sorted, organized, and formatted.

Too busy to build your perfect isort configuration? For curated common configurations, see isort's built-in
profiles.

Python Version Copy Chapter

Tells isort to set the known standard library based on the specified Python version. Default is to assume any Python 3 version could be the target, and use a union of all stdlib modules across versions. If auto is specified, the version of the interpreter used to run isort (currently: 39) will be used.

Type: String
Default: py3
Config default: 3
Python & Config File Name: py_version
CLI Flags:

• --py
• --python-version

Examples:

Example `.isort.cfg` Copy Section

[settings]
py_version=39

Example `pyproject.toml` Copy Section

[tool.isort]
py_version=39

Example cli usage Copy Section

isort --py 39

Force To Top Copy Chapter

Force specific imports to the top of their appropriate section.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: force_to_top
CLI Flags:

• -t
• --top

Skip Copy Chapter

Files that isort should skip over. If you want to skip multiple files you should specify twice: --skip file1 --skip file2. Values can be file names, directory names or file paths. To skip all files in a nested path, use --skip-glob. To even skip matching files that have been specified on the command line, use --filter-files.

Type: List of Strings
Default: ('.bzr', '.direnv', '.eggs', '.git', '.hg', '.mypy_cache', '.nox', '.pants.d', '.pytype' '.svn', '.tox', '.venv', '__pypackages__', '_build', 'buck-out', 'build', 'dist', 'node_modules', 'venv')
Config default: ['.bzr', '.direnv', '.eggs', '.git', '.hg', '.mypy_cache', '.nox', '.pants.d', '.svn', '.tox', '.venv', '__pypackages__', '_build', 'buck-out', 'build', 'dist', 'node_modules', 'venv']
Python & Config File Name: skip
CLI Flags:

• -s
• --skip

Examples:

Example `.isort.cfg` Copy Section

[settings]
skip=.gitignore,.dockerignore

Example `pyproject.toml` Copy Section

[tool.isort]
skip = [".gitignore", ".dockerignore"]

Extend Skip Copy Chapter

Extends --skip to add additional files that isort should skip over. If you want to skip multiple files you should specify twice: --skip file1 --skip file2. Values can be file names, directory names or file paths. To skip all files in a nested path, use --skip-glob. To even skip matching files that have been specified on the command line, use --filter-files.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: extend_skip
CLI Flags:

• --extend-skip

Examples:

Example `.isort.cfg` Copy Section

[settings]
extend_skip=.md,.json

Example `pyproject.toml` Copy Section

[tool.isort]
extend_skip = [".md", ".json"]

Skip Glob Copy Chapter

Files that isort should skip over. To even skip matching files that have been specified on the command line, use --filter-files.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: skip_glob
CLI Flags:

• --sg
• --skip-glob

Examples:

Example `.isort.cfg` Copy Section

[settings]
skip_glob=docs/*

Example `pyproject.toml` Copy Section

[tool.isort]
skip_glob = ["docs/*"]

Extend Skip Glob Copy Chapter

Additional files that isort should skip over (extending --skip-glob). To even skip matching files that have been specified on the command line, use --filter-files.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: extend_skip_glob
CLI Flags:

• --extend-skip-glob

Examples:

Example `.isort.cfg` Copy Section

[settings]
extend_skip_glob=my_*_module.py,test/*

Example `pyproject.toml` Copy Section

[tool.isort]
extend_skip_glob = ["my_*_module.py", "test/*"]

Skip Gitignore Copy Chapter

Treat project as a git repository and ignore files listed in .gitignore. To even skip matching files that have been specified on the command line, use --filter-files.

NOTE: This requires git to be installed and accessible from the same shell as isort.

Type: Bool
Default: False
Config default: false
Python & Config File Name: skip_gitignore
CLI Flags:

• --gitignore
• --skip-gitignore

Line Length Copy Chapter

The max length of an import line (used for wrapping long imports).

Type: Int
Default: 79
Config default: 79
Python & Config File Name: line_length
CLI Flags:

• -l
• -w
• --line-length
• --line-width

Wrap Length Copy Chapter

Specifies how long lines that are wrapped should be, if not set line_length is used.
NOTE: wrap_length must be LOWER than or equal to line_length.

Type: Int
Default: 0
Config default: 0
Python & Config File Name: wrap_length
CLI Flags:

• --wl
• --wrap-length

Line Ending Copy Chapter

Forces line endings to the specified value. If not set, values will be guessed per-file.

Type: String
Default:
Config default:
Python & Config File Name: line_ending
CLI Flags:

• --le
• --line-ending

Sort Re-exports Copy Chapter

Specifies whether to sort re-exports (__all__ collections) automatically.

Type: Bool
Default: False
Config default: false
Python & Config File Name: sort_reexports
CLI Flags:

• --srx
• --sort-reexports

Sections Copy Chapter

What sections isort should display imports for and in what order

Type: List of Strings
Default: ('FUTURE', 'STDLIB', 'THIRDPARTY', 'FIRSTPARTY', 'LOCALFOLDER')
Config default: ['FUTURE', 'STDLIB', 'THIRDPARTY', 'FIRSTPARTY', 'LOCALFOLDER']
Python & Config File Name: sections
CLI Flags: Not Supported

No Sections Copy Chapter

Put all imports into the same section bucket

Type: Bool
Default: False
Config default: false
Python & Config File Name: no_sections
CLI Flags:

• --ds
• --no-sections

Known Future Library Copy Chapter

Force isort to recognize a module as part of Python's internal future compatibility libraries. WARNING: this overrides the behavior of future handling and therefore can result in code that can't execute. If you're looking to add dependencies such as six, a better option is to create another section below --future using custom sections. See: https://github.com/PyCQA/isort#custom-sections-and-ordering and the discussion here: https://github.com/PyCQA/isort/issues/1463.

Type: List of Strings
Default: ('__future__',)
Config default: ['__future__']
Python & Config File Name: known_future_library
CLI Flags:

• -f
• --future

Known Third Party Copy Chapter

Force isort to recognize a module as being part of a third party library.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: known_third_party
CLI Flags:

• -o
• --thirdparty

Examples:

Example `.isort.cfg` Copy Section

[settings]
known_third_party=my_module1,my_module2

Example `pyproject.toml` Copy Section

[tool.isort]
known_third_party = ["my_module1", "my_module2"]

Known First Party Copy Chapter

Force isort to recognize a module as being part of the current python project.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: known_first_party
CLI Flags:

• -p
• --project

Examples:

Example `.isort.cfg` Copy Section

[settings]
known_first_party=my_module1,my_module2

Example `pyproject.toml` Copy Section

[tool.isort]
known_first_party = ["my_module1", "my_module2"]

Known Local Folder Copy Chapter

Force isort to recognize a module as being a local folder. Generally, this is reserved for relative imports (from . import module).

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: known_local_folder
CLI Flags:

• --known-local-folder

Examples:

Example `.isort.cfg` Copy Section

[settings]
known_local_folder=my_module1,my_module2

Example `pyproject.toml` Copy Section

[tool.isort]
known_local_folder = ["my_module1", "my_module2"]

Known Standard Library Copy Chapter

Force isort to recognize a module as part of Python's standard library.

Type: List of Strings
Default: ('_ast', '_dummy_thread', '_thread', 'abc', 'aifc', 'argparse', 'array', 'ast', 'asynchat', 'asyncio', 'asyncore', 'atexit', 'audioop', 'base64', 'bdb', 'binascii', 'binhex', 'bisect', 'builtins', 'bz2', 'cProfile', 'calendar', 'cgi', 'cgitb', 'chunk', 'cmath', 'cmd', 'code', 'codecs', 'codeop', 'collections', 'colorsys', 'compileall', 'concurrent', 'configparser', 'contextlib', 'contextvars', 'copy', 'copyreg', 'crypt', 'csv', 'ctypes', 'curses', 'dataclasses', 'datetime', 'dbm', 'decimal', 'difflib', 'dis', 'distutils', 'doctest', 'dummy_threading', 'email', 'encodings', 'ensurepip', 'enum', 'errno', 'faulthandler', 'fcntl', 'filecmp', 'fileinput', 'fnmatch', 'formatter', 'fpectl', 'fractions', 'ftplib', 'functools', 'gc', 'getopt', 'getpass', 'gettext', 'glob', 'graphlib', 'grp', 'gzip', 'hashlib', 'heapq', 'hmac', 'html', 'http', 'imaplib', 'imghdr', 'imp', 'importlib', 'inspect', 'io', 'ipaddress', 'itertools', 'json', 'keyword', 'lib2to3', 'linecache', 'locale', 'logging', 'lzma', 'macpath', 'mailbox', 'mailcap', 'marshal', 'math', 'mimetypes', 'mmap', 'modulefinder', 'msilib', 'msvcrt', 'multiprocessing', 'netrc', 'nis', 'nntplib', 'ntpath', 'numbers', 'operator', 'optparse', 'os', 'ossaudiodev', 'parser', 'pathlib', 'pdb', 'pickle', 'pickletools', 'pipes', 'pkgutil', 'platform', 'plistlib', 'poplib', 'posix', 'posixpath', 'pprint', 'profile', 'pstats', 'pty', 'pwd', 'py_compile', 'pyclbr', 'pydoc', 'queue', 'quopri', 'random', 're', 'readline', 'reprlib', 'resource', 'rlcompleter', 'runpy', 'sched', 'secrets', 'select', 'selectors', 'shelve', 'shlex', 'shutil', 'signal', 'site', 'smtpd', 'smtplib', 'sndhdr', 'socket', 'socketserver', 'spwd', 'sqlite3', 'sre', 'sre_compile', 'sre_constants', 'sre_parse', 'ssl', 'stat', 'statistics', 'string', 'stringprep', 'struct', 'subprocess', 'sunau', 'symbol', 'symtable', 'sys', 'sysconfig', 'syslog', 'tabnanny', 'tarfile', 'telnetlib', 'tempfile', 'termios', 'test', 'textwrap', 'threading', 'time', 'timeit', 'tkinter', 'token', 'tokenize', 'trace', 'traceback', 'tracemalloc', 'tty', 'turtle', 'turtledemo', 'types', 'typing', 'unicodedata', 'unittest', 'urllib', 'uu', 'uuid', 'venv', 'warnings', 'wave', 'weakref', 'webbrowser', 'winreg', 'winsound', 'wsgiref', 'xdrlib', 'xml', 'xmlrpc', 'zipapp', 'zipfile', 'zipimport', 'zlib', 'zoneinfo')
Config default: ['_ast', '_dummy_thread', '_thread', 'abc', 'aifc', 'argparse', 'array', 'ast', 'asynchat', 'asyncio', 'asyncore', 'atexit', 'audioop', 'base64', 'bdb', 'binascii', 'binhex', 'bisect', 'builtins', 'bz2', 'cProfile', 'calendar', 'cgi', 'cgitb', 'chunk', 'cmath', 'cmd', 'code', 'codecs', 'codeop', 'collections', 'colorsys', 'compileall', 'concurrent', 'configparser', 'contextlib', 'contextvars', 'copy', 'copyreg', 'crypt', 'csv', 'ctypes', 'curses', 'dataclasses', 'datetime', 'dbm', 'decimal', 'difflib', 'dis', 'distutils', 'doctest', 'dummy_threading', 'email', 'encodings', 'ensurepip', 'enum', 'errno', 'faulthandler', 'fcntl', 'filecmp', 'fileinput', 'fnmatch', 'formatter', 'fpectl', 'fractions', 'ftplib', 'functools', 'gc', 'getopt', 'getpass', 'gettext', 'glob', 'graphlib', 'grp', 'gzip', 'hashlib', 'heapq', 'hmac', 'html', 'http', 'imaplib', 'imghdr', 'imp', 'importlib', 'inspect', 'io', 'ipaddress', 'itertools', 'json', 'keyword', 'lib2to3', 'linecache', 'locale', 'logging', 'lzma', 'macpath', 'mailbox', 'mailcap', 'marshal', 'math', 'mimetypes', 'mmap', 'modulefinder', 'msilib', 'msvcrt', 'multiprocessing', 'netrc', 'nis', 'nntplib', 'ntpath', 'numbers', 'operator', 'optparse', 'os', 'ossaudiodev', 'parser', 'pathlib', 'pdb', 'pickle', 'pickletools', 'pipes', 'pkgutil', 'platform', 'plistlib', 'poplib', 'posix', 'posixpath', 'pprint', 'profile', 'pstats', 'pty', 'pwd', 'py_compile', 'pyclbr', 'pydoc', 'queue', 'quopri', 'random', 're', 'readline', 'reprlib', 'resource', 'rlcompleter', 'runpy', 'sched', 'secrets', 'select', 'selectors', 'shelve', 'shlex', 'shutil', 'signal', 'site', 'smtpd', 'smtplib', 'sndhdr', 'socket', 'socketserver', 'spwd', 'sqlite3', 'sre', 'sre_compile', 'sre_constants', 'sre_parse', 'ssl', 'stat', 'statistics', 'string', 'stringprep', 'struct', 'subprocess', 'sunau', 'symbol', 'symtable', 'sys', 'sysconfig', 'syslog', 'tabnanny', 'tarfile', 'telnetlib', 'tempfile', 'termios', 'test', 'textwrap', 'threading', 'time', 'timeit', 'tkinter', 'token', 'tokenize', 'trace', 'traceback', 'tracemalloc', 'tty', 'turtle', 'turtledemo', 'types', 'typing', 'unicodedata', 'unittest', 'urllib', 'uu', 'uuid', 'venv', 'warnings', 'wave', 'weakref', 'webbrowser', 'winreg', 'winsound', 'wsgiref', 'xdrlib', 'xml', 'xmlrpc', 'zipapp', 'zipfile', 'zipimport', 'zlib', 'zoneinfo']
Python & Config File Name: known_standard_library
CLI Flags:

• -b
• --builtin

Examples:

Example `.isort.cfg` Copy Section

[settings]
known_standard_library=my_module1,my_module2

Example `pyproject.toml` Copy Section

[tool.isort]
known_standard_library = ["my_module1", "my_module2"]

Extra Standard Library Copy Chapter

Extra modules to be included in the list of ones in Python's standard library.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: extra_standard_library
CLI Flags:

• --extra-builtin

Examples:

Example `.isort.cfg` Copy Section

[settings]
extra_standard_library=my_module1,my_module2

Example `pyproject.toml` Copy Section

[tool.isort]
extra_standard_library = ["my_module1", "my_module2"]

Known Other Copy Chapter

known_OTHER is how imports of custom sections are defined. OTHER is a placeholder for the custom section name.

Type: Dict
Default: {}
Config default: {}
Python & Config File Name: known_other
CLI Flags: Not Supported

Examples:

Example `.isort.cfg` Copy Section

[settings]
sections=FUTURE,STDLIB,THIRDPARTY,AIRFLOW,FIRSTPARTY,LOCALFOLDER
known_airflow=airflow

Example `pyproject.toml` Copy Section

[tool.isort]
sections = ['FUTURE', 'STDLIB', 'THIRDPARTY', 'AIRFLOW', 'FIRSTPARTY', 'LOCALFOLDER']
known_airflow = ['airflow']

Multi Line Output Copy Chapter

Multi line output (0-grid, 1-vertical, 2-hanging, 3-vert-hanging, 4-vert-grid, 5-vert-grid-grouped, 6-deprecated-alias-for-5, 7-noqa, 8-vertical-hanging-indent-bracket, 9-vertical-prefix-from-module-import, 10-hanging-indent-with-parentheses).

Type: Wrapmodes
Default: WrapModes.GRID
Config default: WrapModes.GRID
Python & Config File Name: multi_line_output
CLI Flags:

• -m
• --multi-line

Examples:

Example `.isort.cfg` Copy Section

[settings]
multi_line_output=3

Example `pyproject.toml` Copy Section

[tool.isort]
multi_line_output = 3

Forced Separate Copy Chapter

Force certain sub modules to show separately

Type: List of Strings
Default: ()
Config default: []
Python & Config File Name: forced_separate
CLI Flags:

• --fs
• --forced-separate

Examples:

Example `.isort.cfg` Copy Section

[settings]
forced_separate=glob_exp1,glob_exp2

Example `pyproject.toml` Copy Section

[tool.isort]
forced_separate = ["glob_exp1", "glob_exp2"]

Indent Copy Chapter

String to place for indents defaults to " " (4 spaces).

Type: String
Default:
Config default:
Python & Config File Name: indent
CLI Flags:

• -i
• --indent

Comment Prefix Copy Chapter

Allows customizing how isort prefixes comments that it adds or modifies on import linesGenerally # (two spaces before a pound symbol) is use, though one space is also common.

Type: String
Default: #
Config default: #
Python & Config File Name: comment_prefix
CLI Flags: Not Supported

Length Sort Copy Chapter

Sort imports by their string length.

Type: Bool
Default: False
Config default: false
Python & Config File Name: length_sort
CLI Flags:

• --ls
• --length-sort

Length Sort Straight Copy Chapter

Sort straight imports by their string length. Similar to length_sort but applies only to straight imports and doesn't affect from imports.

Type: Bool
Default: False
Config default: false
Python & Config File Name: length_sort_straight
CLI Flags:

• --lss
• --length-sort-straight

Length Sort Sections Copy Chapter

Sort the given sections by length

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: length_sort_sections
CLI Flags: Not Supported

Examples:

Example `.isort.cfg` Copy Section

[settings]
length_sort_sections=future,stdlib

Example `pyproject.toml` Copy Section

[tool.isort]
length_sort_sections = ["future", "stdlib"]

Add Imports Copy Chapter

Adds the specified import line to all files, automatically determining correct placement.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: add_imports
CLI Flags:

• -a
• --add-import

Examples:

Example `.isort.cfg` Copy Section

[settings]
add_imports=import os,import json

Example `pyproject.toml` Copy Section

[tool.isort]
add_imports = ["import os", "import json"]

Remove Imports Copy Chapter

Removes the specified import from all files.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: remove_imports
CLI Flags:

• --rm
• --remove-import

Examples:

Example `.isort.cfg` Copy Section

[settings]
remove_imports=os,json

Example `pyproject.toml` Copy Section

[tool.isort]
remove_imports = ["os", "json"]

Append Only Copy Chapter

Only adds the imports specified in --add-import if the file contains existing imports.

Type: Bool
Default: False
Config default: false
Python & Config File Name: append_only
CLI Flags:

• --append
• --append-only

Reverse Relative Copy Chapter

Reverse order of relative imports.

Type: Bool
Default: False
Config default: false
Python & Config File Name: reverse_relative
CLI Flags:

• --rr
• --reverse-relative

Force Single Line Copy Chapter

Forces all from imports to appear on their own line

Type: Bool
Default: False
Config default: false
Python & Config File Name: force_single_line
CLI Flags:

• --sl
• --force-single-line-imports

Single Line Exclusions Copy Chapter

One or more modules to exclude from the single line rule.

Type: List of Strings
Default: ()
Config default: []
Python & Config File Name: single_line_exclusions
CLI Flags:

• --nsl
• --single-line-exclusions

Examples:

Example `.isort.cfg` Copy Section

[settings]
single_line_exclusions=os,json

Example `pyproject.toml` Copy Section

[tool.isort]
single_line_exclusions = ["os", "json"]

Default Section Copy Chapter

Sets the default section for import options: ('FUTURE', 'STDLIB', 'THIRDPARTY', 'FIRSTPARTY', 'LOCALFOLDER')

Type: String
Default: THIRDPARTY
Config default: THIRDPARTY
Python & Config File Name: default_section
CLI Flags:

• --sd
• --section-default

Import Headings Copy Chapter

A mapping of import sections to import heading comments that should show above them.

Type: Dict
Default: {}
Config default: {}
Python & Config File Name: import_headings
CLI Flags: Not Supported

Import Footers Copy Chapter

A mapping of import sections to import footer comments that should show below them.

Type: Dict
Default: {}
Config default: {}
Python & Config File Name: import_footers
CLI Flags: Not Supported

Balanced Wrapping Copy Chapter

Balances wrapping to produce the most consistent line length possible

Type: Bool
Default: False
Config default: false
Python & Config File Name: balanced_wrapping
CLI Flags:

• -e
• --balanced

Use Parentheses Copy Chapter

Use parentheses for line continuation on length limit instead of backslashes. NOTE: This is separate from wrap modes, and only affects how individual lines that are too long get continued, not sections of multiple imports.

Type: Bool
Default: False
Config default: false
Python & Config File Name: use_parentheses
CLI Flags:

• --up
• --use-parentheses

Order By Type Copy Chapter

Order imports by type, which is determined by case, in addition to alphabetically.

NOTE: type here refers to the implied type from the import name capitalization.
isort does not do type introspection for the imports. These "types" are simply: CONSTANT_VARIABLE, CamelCaseClass, variable_or_function. If your project follows PEP8 or a related coding standard and has many imports this is a good default, otherwise you likely will want to turn it off. From the CLI the --dont-order-by-type option will turn this off.

Type: Bool
Default: True
Config default: true
Python & Config File Name: order_by_type
CLI Flags:

• --ot
• --order-by-type

Atomic Copy Chapter

Ensures the output doesn't save if the resulting file contains syntax errors.

Type: Bool
Default: False
Config default: false
Python & Config File Name: atomic
CLI Flags:

• --ac
• --atomic

Lines Before Imports Copy Chapter

The number of blank lines to place before imports. -1 for automatic determination

Type: Int
Default: -1
Config default: -1
Python & Config File Name: lines_before_imports
CLI Flags:

• --lbi
• --lines-before-imports

Lines After Imports Copy Chapter

The number of blank lines to place after imports. -1 for automatic determination

Type: Int
Default: -1
Config default: -1
Python & Config File Name: lines_after_imports
CLI Flags:

• --lai
• --lines-after-imports

Lines Between Sections Copy Chapter

The number of lines to place between sections

Type: Int
Default: 1
Config default: 1
Python & Config File Name: lines_between_sections
CLI Flags: Not Supported

Lines Between Types Copy Chapter

The number of lines to place between direct and from imports

Type: Int
Default: 0
Config default: 0
Python & Config File Name: lines_between_types
CLI Flags:

• --lbt
• --lines-between-types

Combine As Imports Copy Chapter

Combines as imports on the same line.

Type: Bool
Default: False
Config default: false
Python & Config File Name: combine_as_imports
CLI Flags:

• --ca
• --combine-as

Combine Star Copy Chapter

Ensures that if a star import is present, nothing else is imported from that namespace.

Type: Bool
Default: False
Config default: false
Python & Config File Name: combine_star
CLI Flags:

• --cs
• --combine-star

Include Trailing Comma Copy Chapter

Includes a trailing comma on multi line imports that include parentheses.

Type: Bool
Default: False
Config default: false
Python & Config File Name: include_trailing_comma
CLI Flags:

• --tc
• --trailing-comma

Split on Trailing Comma Copy Chapter

Split imports list followed by a trailing comma into VERTICAL_HANGING_INDENT mode. This follows Black style magic comma.

Type: Bool
Default: False
Config default: false
Python & Config File Name: split_on_trailing_comma
CLI Flags:

• --split-on-trailing-comma

From First Copy Chapter

Switches the typical ordering preference, showing from imports first then straight ones.

Type: Bool
Default: False
Config default: false
Python & Config File Name: from_first
CLI Flags:

• --ff
• --from-first

Verbose Copy Chapter

Shows verbose output, such as when files are skipped or when a check is successful.

Type: Bool
Default: False
Config default: false
Python & Config File Name: verbose
CLI Flags:

• -v
• --verbose

Quiet Copy Chapter

Shows extra quiet output, only errors are outputted.

Type: Bool
Default: False
Config default: false
Python & Config File Name: quiet
CLI Flags:

• -q
• --quiet

Force Adds Copy Chapter

Forces import adds even if the original file is empty.

Type: Bool
Default: False
Config default: false
Python & Config File Name: force_adds
CLI Flags:

• --af
• --force-adds

Force Alphabetical Sort Within Sections Copy Chapter

Force all imports to be sorted alphabetically within a section

Type: Bool
Default: False
Config default: false
Python & Config File Name: force_alphabetical_sort_within_sections
CLI Flags:

• --fass
• --force-alphabetical-sort-within-sections

Force Alphabetical Sort Copy Chapter

Force all imports to be sorted as a single section

Type: Bool
Default: False
Config default: false
Python & Config File Name: force_alphabetical_sort
CLI Flags:

• --fas
• --force-alphabetical-sort

Force Grid Wrap Copy Chapter

Force number of from imports (defaults to 2 when passed as CLI flag without value) to be grid wrapped regardless of line length. If 0 is passed in (the global default) only line length is considered.

Type: Int
Default: 0
Config default: 0
Python & Config File Name: force_grid_wrap
CLI Flags:

• --fgw
• --force-grid-wrap

Force Sort Within Sections Copy Chapter

Don't sort straight-style imports (like import sys) before from-style imports (like from itertools import groupby). Instead, sort the imports by module, independent of import style.

Type: Bool
Default: False
Config default: false
Python & Config File Name: force_sort_within_sections
CLI Flags:

• --fss
• --force-sort-within-sections

Lexicographical Copy Chapter

Lexicographical order is strictly alphabetical order. For example by default isort will sort 1, 10, 2 into 1, 2, 10 - but with lexicographical sorting enabled it will remain 1, 10, 2.

Type: Bool
Default: False
Config default: false
Python & Config File Name: lexicographical
CLI Flags: Not Supported

Group By Package Copy Chapter

If True isort will automatically create section groups by the top-level package they come from.

Type: Bool
Default: False
Config default: false
Python & Config File Name: group_by_package
CLI Flags: Not Supported

Separate Packages Copy Chapter

Separate packages within the listed sections with newlines.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: separate_packages
CLI Flags: Not Supported

Examples:

Example `.isort.cfg` Copy Section

[settings]
separate_packages=THIRDPARTY

Example `pyproject.toml` Copy Section

[tool.isort]
separate_packages = ["THIRDPARTY"]

Example before: Copy Section

import os
import sys

from django.db.models.signals import m2m_changed
from django.utils import functional
from django_filters import BooleanFilter
from junitparser import JUnitXml
from loguru import logger

Example after: Copy Section

import os
import sys

from django.db.models.signals import m2m_changed
from django.utils import functional

from django_filters import BooleanFilter

from junitparser import JUnitXml

from loguru import logger

Ignore Whitespace Copy Chapter

Tells isort to ignore whitespace differences when --check-only is being used.

Type: Bool
Default: False
Config default: false
Python & Config File Name: ignore_whitespace
CLI Flags:

• --ws
• --ignore-whitespace

No Lines Before Copy Chapter

Sections which should not be split with previous by empty lines

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: no_lines_before
CLI Flags:

• --nlb
• --no-lines-before

Examples:

Example `.isort.cfg` Copy Section

[settings]
no_lines_before=future,stdlib

Example `pyproject.toml` Copy Section

[tool.isort]
no_lines_before = ["future", "stdlib"]

No Inline Sort Copy Chapter

Leaves from imports with multiple imports 'as-is' (e.g. from foo import a, c ,b).

Type: Bool
Default: False
Config default: false
Python & Config File Name: no_inline_sort
CLI Flags:

• --nis
• --no-inline-sort

Ignore Comments Copy Chapter

If enabled, isort will strip comments that exist within import lines.

Type: Bool
Default: False
Config default: false
Python & Config File Name: ignore_comments
CLI Flags: Not Supported

Case Sensitive Copy Chapter

Tells isort to include casing when sorting module names

Type: Bool
Default: False
Config default: false
Python & Config File Name: case_sensitive
CLI Flags:

• --case-sensitive

Virtual Env Copy Chapter

Virtual environment to use for determining whether a package is third-party

Type: String
Default:
Config default:
Python & Config File Name: virtual_env
CLI Flags:

• --virtual-env

Conda Env Copy Chapter

Conda environment to use for determining whether a package is third-party

Type: String
Default:
Config default:
Python & Config File Name: conda_env
CLI Flags:

• --conda-env

Ensure Newline Before Comments Copy Chapter

Inserts a blank line before a comment following an import.

Type: Bool
Default: False
Config default: false
Python & Config File Name: ensure_newline_before_comments
CLI Flags:

• -n
• --ensure-newline-before-comments

Profile Copy Chapter

Base profile type to use for configuration. Profiles include: black, django,
pycharm, google, open_stack, plone, attrs, hug, wemake, appnexus. As well as
any shared
profiles.

Type: String
Default:
Config default:
Python & Config File Name: profile
CLI Flags:

• --profile

Honor Noqa Copy Chapter

Tells isort to honor noqa comments to enforce skipping those comments.

Type: Bool
Default: False
Config default: false
Python & Config File Name: honor_noqa
CLI Flags:

• --honor-noqa

Src Paths Copy Chapter

Add an explicitly defined source path (modules within src paths have their imports automatically categorized as first_party). Glob expansion (* and **) is supported for this option.

Type: List of Strings
Default: ()
Config default: []
Python & Config File Name: src_paths
CLI Flags:

• --src
• --src-path

Examples:

Example `.isort.cfg` Copy Section

[settings]
src_paths = src,tests

Example `pyproject.toml` Copy Section

[tool.isort]
src_paths = ["src", "tests"]

Remove Redundant Aliases Copy Chapter

Tells isort to remove redundant aliases from imports, such as import os as os. This defaults to False simply because some projects use these seemingly useless aliases to signify intent and change behaviour.

Type: Bool
Default: False
Config default: false
Python & Config File Name: remove_redundant_aliases
CLI Flags:

• --remove-redundant-aliases

Float To Top Copy Chapter

Causes all non-indented imports to float to the top of the file having its imports sorted (immediately below the top of file comment).
This can be an excellent shortcut for collecting imports every once in a while when you place them in the middle of a file to avoid context switching.

NOTE: It currently doesn't work with cimports and introduces some extra over-head and a performance penalty.

Type: Bool
Default: False
Config default: false
Python & Config File Name: float_to_top
CLI Flags:

• --float-to-top

Filter Files Copy Chapter

Tells isort to filter files even when they are explicitly passed in as part of the CLI command.

Type: Bool
Default: False
Config default: false
Python & Config File Name: filter_files
CLI Flags:

• --filter-files

Formatter Copy Chapter

Specifies the name of a formatting plugin to use when producing output.

Type: String
Default:
Config default:
Python & Config File Name: formatter
CLI Flags:

• --formatter

Formatting Function Copy Chapter

The fully qualified Python path of a function to apply to format code sorted by isort.

Type: Nonetype
Default: None
Config default:
Python & Config File Name: formatting_function
CLI Flags: Not Supported

Color Output Copy Chapter

Tells isort to use color in terminal output.

Type: Bool
Default: False
Config default: false
Python & Config File Name: color_output
CLI Flags:

• --color

Treat Comments As Code Copy Chapter

Tells isort to treat the specified single line comment(s) as if they are code.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: treat_comments_as_code
CLI Flags:

• --treat-comment-as-code

Examples:

Example `.isort.cfg` Copy Section

[settings]
treat_comments_as_code = # my comment 1, # my other comment

Example `pyproject.toml` Copy Section

[tool.isort]
treat_comments_as_code = ["# my comment 1", "# my other comment"]

Treat All Comments As Code Copy Chapter

Tells isort to treat all single line comments as if they are code.

Type: Bool
Default: False
Config default: false
Python & Config File Name: treat_all_comments_as_code
CLI Flags:

• --treat-all-comment-as-code

Supported Extensions Copy Chapter

Specifies what extensions isort can be run against.

Type: List of Strings
Default: ('pxd', 'py', 'pyi', 'pyx')
Config default: ['pxd', 'py', 'pyi', 'pyx']
Python & Config File Name: supported_extensions
CLI Flags:

• --ext
• --extension
• --supported-extension

Examples:

Example `.isort.cfg` Copy Section

[settings]
supported_extensions=pyw,ext

Example `pyproject.toml` Copy Section

[tool.isort]
supported_extensions = ["pyw", "ext"]

Blocked Extensions Copy Chapter

Specifies what extensions isort can never be run against.

Type: List of Strings
Default: ('pex',)
Config default: ['pex']
Python & Config File Name: blocked_extensions
CLI Flags:

• --blocked-extension

Examples:

Example `.isort.cfg` Copy Section

[settings]
blocked_extensions=pyw,pyc

Example `pyproject.toml` Copy Section

[tool.isort]
blocked_extensions = ["pyw", "pyc"]

Constants Copy Chapter

An override list of tokens to always recognize as a CONSTANT for order_by_type regardless of casing.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: constants
CLI Flags: Not Supported

Classes Copy Chapter

An override list of tokens to always recognize as a Class for order_by_type regardless of casing.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: classes
CLI Flags: Not Supported

Variables Copy Chapter

An override list of tokens to always recognize as a var for order_by_type regardless of casing.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: variables
CLI Flags: Not Supported

Dedup Headings Copy Chapter

Tells isort to only show an identical custom import heading comment once, even if there are multiple sections with the comment set.

Type: Bool
Default: False
Config default: false
Python & Config File Name: dedup_headings
CLI Flags:

• --dedup-headings

Only Sections Copy Chapter

Causes imports to be sorted based on their sections like STDLIB, THIRDPARTY, etc. Within sections, the imports are ordered by their import style and the imports with the same style maintain their relative positions.

Type: Bool
Default: False
Config default: false
Python & Config File Name: only_sections
CLI Flags:

• --only-sections
• --os

Only Modified Copy Chapter

Suppresses verbose output for non-modified files.

Type: Bool
Default: False
Config default: false
Python & Config File Name: only_modified
CLI Flags:

• --only-modified
• --om

Combine Straight Imports Copy Chapter

Combines all the bare straight imports of the same section in a single line. Won't work with sections which have 'as' imports

Type: Bool
Default: False
Config default: false
Python & Config File Name: combine_straight_imports
CLI Flags:

• --combine-straight-imports
• --csi

Auto Identify Namespace Packages Copy Chapter

Automatically determine local namespace packages, generally by lack of any src files before a src containing directory.

Type: Bool
Default: True
Config default: true
Python & Config File Name: auto_identify_namespace_packages
CLI Flags: Not Supported

Namespace Packages Copy Chapter

Manually specify one or more namespace packages.

Type: List of Strings
Default: frozenset()
Config default: []
Python & Config File Name: namespace_packages
CLI Flags: Not Supported

Follow Links Copy Chapter

If True isort will follow symbolic links when doing recursive sorting.

Type: Bool
Default: True
Config default: true
Python & Config File Name: follow_links
CLI Flags: Not Supported

Indented Import Headings Copy Chapter

If True isort will apply import headings to indented imports the same way it does unindented ones.

Type: Bool
Default: True
Config default: true
Python & Config File Name: indented_import_headings
CLI Flags: Not Supported

Honor Case In Force Sorted Sections Copy Chapter

Honor --case-sensitive when --force-sort-within-sections is being used. Without this option set, --order-by-type decides module name ordering too.

Type: Bool
Default: False
Config default: false
Python & Config File Name: honor_case_in_force_sorted_sections
CLI Flags:

• --hcss
• --honor-case-in-force-sorted-sections

Sort Relative In Force Sorted Sections Copy Chapter

When using --force-sort-within-sections, sort relative imports the same way as they are sorted when not using that setting.

Type: Bool
Default: False
Config default: false
Python & Config File Name: sort_relative_in_force_sorted_sections
CLI Flags:

• --srss
• --sort-relative-in-force-sorted-sections

Overwrite In Place Copy Chapter

Tells isort to overwrite in place using the same file handle. Comes at a performance and memory usage penalty over its standard approach but ensures all file flags and modes stay unchanged.

Type: Bool
Default: False
Config default: false
Python & Config File Name: overwrite_in_place
CLI Flags:

• --overwrite-in-place

Reverse Sort Copy Chapter

Reverses the ordering of imports.

Type: Bool
Default: False
Config default: false
Python & Config File Name: reverse_sort
CLI Flags:

• --reverse-sort

Star First Copy Chapter

Forces star imports above others to avoid overriding directly imported variables.

Type: Bool
Default: False
Config default: false
Python & Config File Name: star_first
CLI Flags:

• --star-first

Format Error Copy Chapter

Override the format used to print errors.

Type: String
Default: {error}: {message}
Config default: {error}: {message}
Python & Config File Name: format_error
CLI Flags:

• --format-error

Format Success Copy Chapter

Override the format used to print success.

Type: String
Default: {success}: {message}
Config default: {success}: {message}
Python & Config File Name: format_success
CLI Flags:

• --format-success

Sort Order Copy Chapter

Specify sorting function. Can be built in (natural[default] = force numbers to be sequential, native = Python's built-in sorted function) or an installable plugin.

Type: String
Default: natural
Config default: natural
Python & Config File Name: sort_order
CLI Flags:

• --sort-order

Show Version Copy Chapter

Displays the currently installed version of isort.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• -V
• --version

Examples:

Example cli usage Copy Section

isort --version

Version Number Copy Chapter

Returns just the current version number without the logo

Type: String
Default: ==SUPPRESS==
Config default: ==SUPPRESS==
Python & Config File Name: Not Supported
CLI Flags:

• --vn
• --version-number

Write To Stdout Copy Chapter

Force resulting output to stdout, instead of in-place.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• -d
• --stdout

Show Config Copy Chapter

See isort's determined config, as well as sources of config options.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• --show-config

Show Files Copy Chapter

See the files isort will be run against with the current config options.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• --show-files

Show Diff Copy Chapter

Prints a diff of all the changes isort would make to a file, instead of changing it in place

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• --df
• --diff

Check Copy Chapter

Checks the file for unsorted / unformatted imports and prints them to the command line without modifying the file. Returns 0 when nothing would change and returns 1 when the file would be reformatted.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• -c
• --check-only
• --check

Settings Path Copy Chapter

Explicitly set the settings path or file instead of auto determining based on file location.

Type: String
Default: None
Config default:
Python & Config File Name: Not Supported
CLI Flags:

• --sp
• --settings-path
• --settings-file
• --settings

Config Root Copy Chapter

Explicitly set the config root for resolving all configs. When used with the --resolve-all-configs flag, isort will look at all sub-folders in this config root to resolve config files and sort files based on the closest available config(if any)

Type: String
Default: None
Config default:
Python & Config File Name: Not Supported
CLI Flags:

• --cr
• --config-root

Resolve All Configs Copy Chapter

Tells isort to resolve the configs for all sub-directories and sort files in terms of its closest config files.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• --resolve-all-configs

Jobs Copy Chapter

Number of files to process in parallel. Negative value means use number of CPUs.

Type: Int
Default: None
Config default:
Python & Config File Name: Not Supported
CLI Flags:

• -j
• --jobs

Ask To Apply Copy Chapter

Tells isort to apply changes interactively.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• --interactive

Files Copy Chapter

One or more Python source files that need their imports sorted.

Type: String
Default: None
Config default:
Python & Config File Name: Not Supported
CLI Flags:

Dont Follow Links Copy Chapter

Tells isort not to follow symlinks that are encountered when running recursively.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• --dont-follow-links

Filename Copy Chapter

Provide the filename associated with a stream.

Type: String
Default: None
Config default:
Python & Config File Name: Not Supported
CLI Flags:

• --filename

Allow Root Copy Chapter

Tells isort not to treat / specially, allowing it to be run against the root dir.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• --allow-root

Dont Float To Top Copy Chapter

Forces --float-to-top setting off. See --float-to-top for more information.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• --dont-float-to-top

Dont Order By Type Copy Chapter

Don't order imports by type, which is determined by case, in addition to alphabetically.

NOTE: type here refers to the implied type from the import name capitalization.
isort does not do type introspection for the imports. These "types" are simply: CONSTANT_VARIABLE, CamelCaseClass, variable_or_function. If your project follows PEP8 or a related coding standard and has many imports this is a good default. You can turn this on from the CLI using --order-by-type.

Type: Bool
Default: False
Config default: false
Python & Config File Name: Not Supported
CLI Flags:

• --dt
• --dont-order-by-type

Ext Format Copy Chapter

Tells isort to format the given files according to an extensions formatting rules.

Type: String
Default: None
Config default:
Python & Config File Name: Not Supported
CLI Flags:

• --ext-format

Deprecated Flags Copy Chapter

==SUPPRESS==

Type: String
Default: None
Config default:
Python & Config File Name: Not Supported
CLI Flags:

• -k
• --keep-direct-and-as