pycqa/isort

A Python utility / library to sort imports.

---

---

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.8+ 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

Installing isort is as simple as:

pip install isort

Using isort

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

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

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

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

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

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)

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

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

See a complete guide here.

Using isort to verify code

The --check-only option

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

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

More info here.

Setuptools integration

Upon installation, isort enables a setuptools command that checks Python files declared by your project.

More info here.

Spread the word

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

For README.md:

[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)

Or README.rst:

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

Security contact information

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

Why isort?

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

isort's Issues

Looks like some code will be deleted

input

import sys
import os
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from model.parser import LogParser
from utils.scribec import send as scribesend

output

import os
import sys

from model.parser import LogParser
from utils.scribec import send as scribesend

looks like sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) is gone.

unexpected extra lines

$subj will be added after every call to this plugin.
to reproduce, just press Ctrl+[ for a few seconds: watch how vertical scrollbar is getting grow...
same for add and remove import...

False settings have no effect

Setting anything to False in the .isort.cfg does not work.

The following .isort.cfg

[settings]
balanced_wrapping=False
length_sort=False
order_by_type=False

is equivalent to

[settings]
balanced_wrapping=True
length_sort=True
order_by_type=True

or even

[settings]
balanced_wrapping=does_not_matter
length_sort=irrelevant
order_by_type

As a workaround, I commented out all settings I wanted to be False, since that is currently the default for all of them:

[settings]
# balanced_wrapping=False
# length_sort=False
# order_by_type=False

order_by_type may have caused unexpected issues

Following the changes for allowing order_by_type (thanks for that by the way)

I get the following diff

@@ -27,13 +27,13 @@
 #       might be a little less Pythonic. See os.system() calls for more
 #       details.

+import StringIO
 import glob
 import os
 import shutil
-import StringIO
 import tempfile
 import time
-from subprocess import Popen, PIPE, STDOUT
+from subprocess import PIPE, Popen, STDOUT

 join = os.path.join

Two issues seem to be present

1. StringIO is moved to the top of the standard lib imports, where I'd expect it to remain alphabetically sorted and only order by type in a from x import YYY, ZzzZzzz, www_www
2. The subprocess import seems to be sorted incorrectly, I was expecting:

from subprocess import PIPE, STDOUT, Popen

list index out of range error

Traceback (most recent call last):
File "/usr/share/apps/kate/plugins/pate/kate/init.py", line 306, in call
return self.f()
File "/home/zaufi/.kde4/share/apps/kate/pate/kate_plugin.py", line 59, in add_imports
document.setText(SortImports(file_contents=document.text(), add_imports=text.split(";")).output)
File "/usr/lib64/python3.3/site-packages/isort/isort.py", line 91, in init
self._parse()
File "/usr/lib64/python3.3/site-packages/isort/isort.py", line 316, in _parse
self.as_map[imports[index -1]] = imports[index + 1]
IndexError: list index out of range

Provide a flag to receive input from stdin

Relating to #38, this would make it even easier to use with M-| in emacs.

Many tools do this by accepting the special file name - as meaning stdin. This can also imply -d

Use tokenizer

I don't think the fix for #67 is quite right.

import os

'\
import foo'

is still parsed incorrectly. isort ends up garbling the syntax into

import os

import foo'

'\

I would recommend using Python tokenizer and blacklisting those lines that are within strings. I think that would be easier than coming up with a custom Python parser.

Shouldn't thread be a standard library? If I force it much more changes

I get this altered sort order. I think thread should be a standard library...

@@ -28,10 +28,10 @@ import os.path
 import re
 import stat
 import sys
-import thread
 from UserDict import UserDict
 from sqlite3 import dbapi2

+import thread
 from translate import __version__ as toolkitversion
 from translate.lang.common import Common
 from translate.misc.multistring import multistring

Then I force it using

known_standard_library=thread

And now the diff is this

@@ -24,14 +24,14 @@
 """

 import logging
-import os.path
 import re
 import stat
-import sys
 import thread
 from UserDict import UserDict
 from sqlite3 import dbapi2

+import os.path
+import sys
 from translate import __version__ as toolkitversion
 from translate.lang.common import Common
 from translate.misc.multistring import multistring

i.e. a lot of standard libraries have been moved to incorrect sections.

Keep current selection when using kate plugin

When sorting, adding, or removing imports using the isort Kate plugin the current selected text becomes un-selected unexpectedly.

Parsing needs to respect quotes

Input:

import os

"""
Let us
import foo
okay?
"""

Corrupted output:

import os

import foo

"""
Let us
okay?
"""

support for pylint/pep8 style error printing, rather than changing the file

It would be nice if I could configure my jnekins box to "UNSTABLE" the build if imports are in the wrong order. For this, isort should leave the files alone and print out error messages for each bad line.

Along with this feature the ability to add:

from django import foo  # isort: disable

would be nice

More optimized plugin integration, avoid replacing all text.

Ideally, isort should keep record of what areas of a file changed. The Kate plugin should then use this data to update the text for only these areas (instead of replacing the entire document text).

Imports should usually be on separate lines

It would be nice to have a configurable option to allow multiple "from a import b" lines, instead of forcing them all to be on a single line, e.g. to allow

from a import b
from a import c

instead of

from a import b, c

PEP 8 says that the latter is "OK", but it seems to be phrased as an exception to the basic idea of "Imports should usually be on separate lines"

Cannot handle non-ASCII characters

Here's two more or less identical python scripts, one of which contains UTF-8 encoded characters:

$ cat test1.py
# -*- coding: utf-8 -*-
"""abc"""
$ cat test2.py
# -*- coding: utf-8 -*-
"""æøå"""
$ python test1.py && echo ok
ok
$ python test2.py && echo ok
ok
$ isort test1.py && echo ok
ok
$ isort test2.py && echo ok
Traceback (most recent call last):
  File "/usr/local/bin/isort", line 43, in <module>
    SortImports(file_name, **arguments)
  File "/usr/local/lib/python2.7/dist-packages/isort/isort.py", line 73, in __init__
    self.in_lines = file_contents.split("\n")
UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 27: ordinal not in range(128)
$ 

Boom!

Allow 2 spaces after an import block

While PEP8 is unclear about how many lines after the import block it does say this:
"Separate top-level function and class definitions with two blank lines."

So in our code we add two lines after imports to closely match our high level double line breaks.

This probably isn't what other people do so being able to set the blank line following an import block would be a good option

[feature] put cursor back to the original position

after any action (add or remove, not talking about sort) it would be nice to have a cursor at the original position.

verify isort doesn't break Python scripts

The process of compiling code into pyc files and checking for syntax errors could be used after and potentially before isort is ran to verify isort does not introduce any errors. If isort does introduce an error, a message would be displayed to the user, and the file would stay at the state it was before isort was ran, with the isort output never being written to the filesystem.

Exclude specific import

There many situations when some imports should not be put at the top, lest it will introduce circularity. These include projects such as Flask apps with HTTP handlers split between separate modules:

# __init__.py

from flask import Flask

app = Flask('myapp')

import myapp.handlers

# handlers.py

from myapp import app

@app.route('index')
def index():
   return "Hello world"

In this example, moving import myapp.handlers to the top will cause circular import error because of app symbol.

We can of course exclude the whole file, but this may be suboptimal. I suggest introducing a directive that allows for more fine-grained skipping, for example:

import myapp.handlers  # isort:skip

Titles added with *every* run.

It looks like when isort is run on multiple times on a file with an .isortrc like this:

[settings]
import_heading_stdlib=Standard Library
import_heading_thirdparty=Third Party
import_heading_localfolder=Local

I'll get a file which looks like this:

# Standard Library
# Standard Library
# Standard Library
import heapq

# Local
from . import util
from .node import nullrev

# Local

# Local

I expect you need a check to see if the comment is already there.

Hanging grid multiline mode

It would be nice to have a new mode, mixing the grid with the hanging indent.

Something like this:

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

It would help to save lines and fits well with long from module paths.

'as' appears to cause issues

For example, in my own project. Before:

import socket
import struct

from parsley import makeProtocol, stack
from twisted.internet import protocol, defer, interfaces
from twisted.python import failure
from zope.interface import implements

import txsocksx.constants as c, txsocksx.errors as e
from txsocksx import grammar

After:

import socket
import struct

import txsocksx.constants as c
from parsley import makeProtocol, stack
from twisted.internet import defer, interfaces, protocol
from twisted.python import failure
from txsocksx import grammar
from zope.interface import implements

import c as e
import e

Option to treat unknown modules as third-party

On most of the projects I work on, everything is namespaced so it's really easy to say --known-first-party=<base namespace>. Unfortunately for lazy people, everything unknown is assumed to be first-party so I have to build a long list of known third-party packages. It'd be really nice if there was a way to simply have isort treat everything not in stdlib or the first-party list as third-party so I would only need to populate the exceptions.

indent string config adds quotation marks to hanging indents

When I run (the current 2.6.1 from PyPI) isort using the command line options like this:

$ isort --multi_line=2 src/**/*.py

my imports get formatted like this:

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

When I try to use the config file to configure indent permanently like this:

$ cat .isort.cfg
[settings]
# [...]
indent='    '

my source gets polluted with quotation marks like this:

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

Seems like the string from the configuration file gets copied without removing the quotation marks.

project level configuration (something that can be checked into git)

I'm working on a project with some funky paths config, which means the project I'm working on is discovered as a thirdy-party lib rather than first-party code.

It would be nice to have a config file ala .pep8 or setup.cfg that can be checked into git.

Import as not sorting in alphabetical order

The following diff is from our code.

I'd expect the current line to remain unchanged. Instead isort breaks this in two but then also sorts it in an order that doesn't seem to follow any logical sort order. Both parse and rich_parse should sort after general. I'd expect this to sort on parse anyway and not on rich_parse.

from translate.misc.multistring import multistring
from translate.storage import base, factory
-from translate.storage.placeables import general, parse as rich_parse
+from translate.storage.placeables import parse as rich_parse
+from translate.storage.placeables import general

typo "setdefualt"

$ isort *
Traceback (most recent call last):
File "/usr/local/bin/isort", line 30, in
SortImports(file_name, **arguments)
File "/usr/local/lib/python2.7/dist-packages/isort/isort.py", line 82, in init
self._parse()
File "/usr/local/lib/python2.7/dist-packages/isort/isort.py", line 273, in _parse
self.imports[module_placment][import_type].setdefualt(from_import, set()).update(imports)
AttributeError: 'dict' object has no attribute 'setdefualt'

Don't install unnecessary dependencies

argparse, configparser, and ordereddict really should not be installed on Python 2.7. At best this is unnecessary. At worst it is clobbering things.

Keep spaces before inline comments

isort currently collapses spaces separating inline comments from import statements into one space.

When I write this:

import a  # useful library

isort removes one of the spaces:

diff [...]

-import a  # useful library
+import a # useful library

According to pep8, [i]nline comments should be separated by at least two spaces from the statement.

I think, isort should keep double spaces if they exist, to keep code adhering to pep8 valid. Perhaps isort should also introduce double spaces, if there is only one, to make the resulting code adhere to pep8.

Follow pep8's lead and use setup.cfg?

pep8 can use the setup.cfg file for project-level config: http://pep8.readthedocs.org/en/latest/intro.html#configuration

What do you think about using that instead of / in addition to the .isort.cfg file to reduce the proliferation of dotfiles inside projects?

beautify __future__

Hi,

Thanks for this great project, I use it via vim and it works very well for me.
I have a little suggestion concerning the __future__ statement. isort formats it like this:

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

I would like to see print_function in the next line:

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

It looks more balanced :) It's not a big thing, I know.

Best,

Laszlo

relative import issue

isort caused a syntax error:

--- a/foo/foo/foo_foo/tests/foo_v0/test_jobs.py
+++ b/foo/foo/foo_foo/tests/foo_v0/test_jobs.py
@@ -6,9 +6,10 @@ from django.test.client import RequestFactory
 from mock import patch
 from model_mommy import mommy

-from ... import models, sproqet_api as sproq_api
-from ... fields.sproqet import SproqetCollection
-from ..utils import fake_spork_client, http_status_codes as status
+from ... import sproqet_api as sproq_api
+from ... import fields.sproqet, models, SproqetCollection
+from ..utils import http_status_codes as status
+from ..utils import fake_spork_client
 from ..utils.misc import SporkPatcherTestCaseMixin
 from .utils.constants import job_clone_uri_name, job_detail_uri_name

Print diff

I'd like to be able to print the diff so that I can see what isort is trying to do before actually writing to the file system. An option like --diff would be fine. Though I kind of like the default behavior of 2to3, which does the safe thing by default by only writing to the file system if the user tells it to. Otherwise it just prints a diff.

isort silently writes output to the current directory, even if run on a different path

It seems like the tool always writes the result into the current directory, which is pretty unexpected. I think you should provide an --inplace option or fail explicitly if you don't know where to save the result.

Currently for the unsuspecting newcomer it seems that the tool does nothing when run on a different path.

Something in __future__ appears to cause issues

For example, in this project's isort.py. Before:

from __future__ import absolute_import, division, print_function, unicode_literals

import copy
import os
from pies import *
from sys import path as PYTHONPATH

from . import settings

After:

from __future__ import absolute_, division, print_function, unicode_literals

import copy
import os
from sys import path as PYTHONPATH

from pies import *

from . import settings

Note the absolute_.

Imports added using -a get appended for files without imports

I have a file in my code base that looks like this:

"""Module docstring"""

class MyClass(object):
    pass

I try to run this:

isort -a "from __future__ import print_function"

Afterwards the file looks like this:

"""Module docstring"""

class MyClass(object):
    pass

from __future__ import print_function

Since __future__ imports need to be at the top of the file, this is invalid syntax.

Imports followed by comment followed by function don't receive enough space (according to pep8)

(TL;DR: I think comments should be ignored when determining what the "next" thing in a file is after imports)

pep8 is happy with the following file:

import sys


# This is a comment
def foo():
    pass

Running isort on it removes one of the newlines between the import and the comment, which makes pep8 unhappy.

The lines_after_imports setting lets us work-around this (which is good 👍), but it means that we always end up with two spaces, even in the cases where pep8 would be happy with only 1.

For example, pep8 is happy with the single space in this case:

import sys

# This is a comment
wibble = 'bar'

P.S. Thanks for all your hard work making a great tool!

Duplicate spaces after `import`

isort creates import lines with multiple spaces like this:

from my_package import  Mod0, Mod1, \
    Mod2, fun1

flake8 will complain about them:

myfile:13:44: E271 multiple spaces after keyword
from my_package import  mod0, mod1, \
                     ^
    Avoid extraneous whitespace around keywords.

When I remove the duplicate space and run isort again, it reappears.

Import that is ignored

I had one weird import in my code that got ignored by isort:

from pkg \
   import stuff, other_suff \
              more_stuff

Sorry if this is fixed already - I only tested with pypi release.

Newlines in input file

The check feature gives a wrong output, if there are newlines in the insert line of the input file.

For example:

from lib import (
  some_object,
  some_other_object)

Here is a test for this problem.

from mock import patch

def test_check_newline_in_imports():
    test_input = "from lib1 import (\n  sub1, sub2\n  sub3)"
    SortImports.file_path = ''  # Add file_path to Class
    with patch('__builtin__.print') as mock_print:
        SortImports(file_path=False, file_contents=test_input, check=True)
    assert 'SUCCESS' in mock_print.call_args[0][0]

Provide a way to output the resulting file to stdout

This is useful for integrating with existing IDEs (esp. Emacs)

'as' appears to still cause issues

Before:

import socket
import struct

from parsley import makeProtocol, stack
from twisted.internet import protocol, defer, interfaces
from twisted.python import failure
from zope.interface import implements

import txsocksx.constants as c, txsocksx.errors as e
from txsocksx import grammar

After:

import socket
import struct

import txsocksx.constants as c
import txsocksx.errors as e
from parsley import makeProtocol, stack
from twisted.internet import defer, interfaces, protocol
from twisted.python import failure
from txsocksx import grammar
from zope.interface import implements

import c
import e

This is better than before, but still somehow ends up with import c and import e.

Implemented a vim plugin, point to it on the readme

I didn't do a pull request adding the vim plugin to your repo, because in the vim world we use some plugin managers that install plugins directly from git repos, and the repos must have the vim plugin structure on the root folder. That would require that I put the vim plugin code on the root of your repo, which would be ugly. So I created the plugin on its own repo, here:

https://github.com/fisadev/vim-isort

Can you point to it on the readme?

Order imports by CONSTANT, Class, function

In our project we decided to break the cluster of imports from a module such that they are grouped not just alphabetically bust by type.

So:

from module import CONSTANT, Class, function

Instead of:

from module import Class, CONSTANT, function

We find the visual order much easier to parse.

isort drops content for line breaks on "."

When I use line breaks in my imports, like this:

from my_lib.my_package.test.level_1.level_2.level_3.level_4.level_5.\
    my_module import my_function

isort drops everything after the \:

-from my_lib.my_package.test.level_1.level_2.level_3.level_4.level_5.\
-    my_module import my_function
+from my_lib.my_package.test.level_1.level_2.level_3.level_4.level_5. import my_function

This of course breaks the code and is obviously not intended. isort should detect the line break, strip the indentation whitespace on the second line, concatenate the import into one and hande that as usual.

Note that there is a . character before the import keyword, which is always invalid syntax.

Also note that the import line isort adds is longer than allowed. I am not sure if this can be fixed together or in a different issue.

Switch to using natsorted

Handle inline comments for imports

Sometimes it is useful to comment imports, e.g. to clarify renames:

from a import f as f_small  # more space efficient implementation
from b import f as f_quick  # more time efficient implementation

Currently isort removes such inline comments:

from a import f as f_small
from b import f as f_quick

isort should reorder and reformat inline comments properly.

Test using nosetests/setuptools/travis-ci

It should be possible to test python projects by running,

python setup.py test in their project directory.

A cool tool for this is:
https://nose.readthedocs.org/en/latest/setuptools_integration.html

It would be great to run these tests on py2-3 on travis-ci

isort plugin/package for Emacs

Hi,

I have written a package to use isort with Emacs - py-isort.el: https://github.com/paetzke/py-isort.el. Maybe you can mention it in the Readme.

Greetings
Friedrich

Order submodules in seperate group

Sometimes you have a submodule in which you want to sort the imports in a seperate group. For example see https://github.com/django/django/blob/master/django/contrib/admin/views/main.py

Could you add a way to configure isort for that case?

For example by adding a 'subpackage' option to the config file.

isort misplaces django.utils.six

from __future__ import unicode_literals

import datetime
from random import randint

from django.core.urlresolvers import reverse
from django.utils.six.moves import xrange
from rest_framework.viewsets import ViewSet

becomes:

from __future__ import unicode_literals

import datetime
from random import randint

from django.core.urlresolvers import reverse
from rest_framework.viewsets import ViewSet

from django.utils.six.moves import xrange