isort Settings

This page is outdated. For up to date information refer to the official configuration documentation.

isort provides several ways to configure its behavior, so that it can work well with your project's unique style guidelines.

isort follows the following priority when applying settings:

• Settings manually passed into the Python SortImports class.
• Settings manually passed into the command line utility.
• Settings placed in a setup.cfg file within the project's directory
• Settings placed in a .isort.cfg file within the project's directory.
• Settings placed in a .isort.cfg file within the users home directory.
• Settings placed in a .editorconfig file within the project's directory.
• Settings placed in a .editorconfig file within the users home directory.

Setting list settings from the command line

When you set a command line argument that can be set more then once (For Example: skip) you must fully specify for each setting. For example to skip file1.py and file2.py do:

isort --skip file1.py --skip file2.py

Command line settings may vary from the config list below. See isort --help for the correct arguments.

Full reference of isort settings

Below is a full reference of every setting isort accepts, alongside a basic explanation of its use:

• force_to_top: Forces a list of imports to the top of their respective section. This works well for handling the unfortunate cases of import dependencies that occur in many projects.

• skip: A list of files to skip sorting completely.

• skip_glob: A list of glob patterns to skip sorting completely.

• not_skip: A list of files to never skip sorting.

• line_length: An integer that represents the longest line-length you want a single import to take. Defaults to 79.

• wrap_length: An integer that represents the longest line-length you want when wrapping. If not set will default to line_length.

• known_future_library: A list of imports that will be forced to display within the future library category.

• known_standard_library: A list of imports that will be forced to display within the standard library category.

• extra_standard_library: Like known_standard_library but appends instead of replacing.

• known_third_party: A list of imports that will be forced to display within the third party category.

• known_first_party: A list of imports that will be forced to display within the first party category.

• virtual_env: Virtual environment to use for determining whether a package is third-party.

• multi_line_output: An integer that represents how you want imports to be displayed if they're long enough to span multiple lines. A full definition of all possible modes can be found here.

• forced_separate: A list of modules that you want to appear in their own separate section. NOTE: This does not work with custom organized sections. For that use known_{section} instead.

• indent: An integer that represents the number of spaces you would like to indent by or Tab to indent by a single tab.

• length_sort: If set to true - imports will be sorted by their length instead of alphabetically.

• force_single_line: If set to true - instead of wrapping multi-line from style imports, each import will be forced to display on its own line.

• force_grid_wrap: Force from imports to be grid wrapped regardless of line length, where the value given is the number of imports allowed before wrapping occurs.

• default_section: The default section to place imports in, if their section can not be automatically determined. FIRSTPARTY, THIRDPARTY, etc.

• import_heading_future: A comment to consistently place directly above future imports.

• import_heading_stdlib: A comment to consistently place directly above imports from the standard library.

• import_heading_thirdparty: A comment to consistently place directly above thirdparty imports.

• import_heading_firstparty: A comment to consistently place directly above imports from the current project.

• import_heading_localfolder: A comment to consistently place directly above imports that start with '.'.

• balanced_wrapping: If set to true - for each multi-line import statement isort will dynamically change the import length to the one that produces the most balanced grid, while staying below the maximum import length defined.

• order_by_type: If set to true - isort will create separate sections within "from" imports for CONSTANTS, Classes, and modules/functions.

• atomic: If set to true - isort will only change a file in place if the resulting file has correct Python syntax. This defaults to false because it can only work if the version of code having it's imports sorted is running the same version of Python as isort itself.

• lines_after_imports: Forces a certain number of lines after the imports and before the first line of functional code. By default this is 2 lines if the first line of code is a class or function. Otherwise it's 1.

• lines_between_types: Forces a certain number of lines between the two import types (import mylib and from mylib import foo) within a section.

• combine_as_imports: If set to true - isort will combine as imports on the same line within for import statements. By default isort forces all as imports to display on their own lines.

• force_adds: If set to true - isort will add imports even if the file specified is currently completely empty.

• combine_star: If set to true - ensures that if a star import is present, nothing else is imported from that namespace.

• verbose: If set to true - isort will print out verbose information such as when a file is skipped intentionally or when a file check is successful.

• settings-path: Can be used from the command line to manually specify the location of a settings file.

• include_trailing_comma: Will set isort to automatically add a trailing comma to the end of from imports.

• use_parentheses: Tells isort to use parenthesis for line continuation instead of \ for lines over the allotted line length limit.

• from_first: If set, from imports will be displayed above normal (straight) imports.

• case_sensitive: If set, import sorting will take case in consideration when sorting.

• add_imports: A comma-delimited list of imports to add to every file ran through isort.

• filter_files: Tells isort to filter files even when they are explicitly passed in as part of the command. This is especially useful to get skip and skip_glob to work when running isort through pre-commit.

• force_sort_within_sections: If set, imports will be sorted within their section independent to the import_type.

• force_alphabetical_sort: If set, forces all imports to be sorted as a single section, instead of within other groups (such as straight vs from).

  For example:

  from os import path
  import os
  

  and not the default behavior of:

  import os
  from os import path
  

• reverse_relative: If set, forces relative import to be sorted as Google style guide.

  For example:

  from . import y
  from ..import x
  

  and not the default behaviour (alphabetical order) of:

  from .. import x
  from . import y
  

• profile: If set, settings will be inherited from named profile. Available profiles can be found on isort/profiles.py.