How to Install isort in Python

isort is a Python tool that sorts imports alphabetically. It also groups them into standard-library, third-party, and local sections. This keeps your code clean and PEP 8 compliant.

isort removes duplicate imports and wraps long import lines. It saves you from manually ordering every import statement. You can run it from the command line, inside Python code, or through editor plugins.

This guide shows you how to install isort in Python step by step. You will also learn how to configure it, run it on your projects, and avoid common errors.

Why Use isort?

Python projects grow fast. Imports pile up at the top of every file. Without a sorter, your imports become messy and inconsistent.

isort fixes this problem automatically. It places imports in the right section and in the right order. Your code reviews become easier because diffs stay small and focused.

Consistent imports also prevent bugs. A missing or duplicated import can break your script at runtime. isort catches these issues before they reach production.

If you already work with tools like Apache Airflow to schedule Python tasks with Airflow, isort fits right into that workflow. Clean imports are the foundation of any reliable pipeline.

Prerequisites

Before you install isort, make sure you have the following:

• Python 3.10 or later installed on your system
• pip package manager available
• A virtual environment activated for your project

You can check your Python version with the command python --version. If pip is missing, install it with python -m ensurepip.

How to Install isort with pip

The simplest way to install isort is through pip. Run this command in your terminal:

 pip install isort 

This downloads the latest stable version from PyPI. If you use a virtual environment, the package installs only for that project.

You can also install isort with your preferred package manager. Here are the alternatives:

 # Using uv uv add isort # Using poetry poetry add isort # Using pipenv pipenv install isort # For a fully isolated installation pipx install isort 

Each method works well. Choose the one that matches your existing development setup.

Installing with Optional Dependencies

isort supports extra features through optional dependencies. If you want isort to read requirements.txt files, install it with the requirements extra:

 pip install isort[requirements] 

For Pipfile support, use the pipfile extra:

 pip install isort[pipfile] 

You can combine both extras in one command:

 pip install isort[requirements,pipfile] 

These extras help isort understand your project dependencies better. They are optional but useful for larger projects.

Verifying the Installation

After installation, confirm that isort is available. Run this command:

 isort --version 

You should see output similar to this:

 _ _ (_) ___ ___ _ __| |_ | |/ _/ / _ \/ '__ _/ | |\__ \/\_\/| | | |_ |_|\___/\___/\_/ \_/ isort your imports, so you don't have to. VERSION 5.13.2 

If the command returns a version number, isort is installed correctly. If you see a "command not found" error, check your PATH or try running python -m isort --version.

Configuring isort

isort works well with default settings. But most projects benefit from a custom configuration. isort reads settings from several file formats.

The tool looks for configuration in this order: .isort.cfg, pyproject.toml, setup.cfg, tox.ini, and .editorconfig.

The pyproject.toml file is the preferred format for modern Python projects. Here is a basic example:

 [tool.isort] profile = "black" line_length = 88 known_first_party = ["my_package"] src_paths = ["src", "tests"] 

This configuration sets the Black profile and tells isort where to find your source files. The known_first_party option helps isort recognize your own modules as local imports.

You can also use a dedicated .isort.cfg file if you prefer a separate config:

 [settings] profile = black line_length = 88 src_paths = isort,test 

Both formats work equally well. Choose the one that fits your project structure.

Using isort from the Command Line

Once installed, you can sort imports across your entire project with one command:

 isort . 

This recursively finds all Python files and sorts their imports. If your project uses a src directory, run this instead:

 isort src 

To sort a single file, pass the filename directly:

 isort my_script.py 

You can also preview changes without applying them:

 isort my_script.py --diff 

The --diff flag shows what isort would change. This is useful for reviewing changes before committing them.

Using isort Inside Python Code

isort is not only a command-line tool. You can use it as a Python library in your scripts. Here is how to sort a file programmatically:

 import isort # Sort a file in place isort.file("pythonfile.py") # Sort a string of code sorted_code = isort.code("import b\nimport a\n") print(sorted_code) 

The isort.file() method sorts imports in a file. The isort.code() method returns a sorted string without touching the file system.

This approach works well when you generate code dynamically. For example, you can sort imports before writing files in a code generation pipeline.

Integrating isort with Black

Black and isort are often used together. Both tools format Python code, but they handle imports differently. Without proper setup, they can conflict and undo each other's changes.

Since isort 5.0.0, you can set the Black profile to resolve conflicts. Add this to your pyproject.toml:

 [tool.isort] profile = "black" 

This single line makes isort compatible with Black's import formatting. It sets the correct multi-line output mode, line length, and trailing comma behavior.

If you use an older version of isort, you can manually configure these options:

 [settings] multi_line_output = 3 include_trailing_comma = True force_grid_wrap = 0 use_parentheses = True ensure_newline_before_comments = True line_length = 88 

These settings align isort's output with Black's style. Your imports stay clean and consistent across both tools.

If you send automated reports or HTML emails from your Python scripts, you already know how much formatting matters. Tools like SendGrid help you deliver clean HTML emails. Clean imports in your codebase keep those scripts maintainable.

Setting Up isort with Pre-commit

Pre-commit hooks run checks before every commit. Adding isort to your pre-commit configuration prevents unsorted imports from entering your repository.

Create a file named .pre-commit-config.yaml in your project root:

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

This configuration runs isort on every commit. The --filter-files flag ensures that isort skips files it cannot parse.

You can combine isort with Black in the same pre-commit file for a complete formatting pipeline.

Common Installation Problems

Most isort installations work without issues. But sometimes you may encounter errors. Here are the most common problems and their solutions.

Problem: "isort: command not found"

This means isort is not on your PATH. Try running it as a Python module instead:

 python -m isort --version 

If that works, your Python environment is fine. You may need to activate your virtual environment or reinstall pip.

Problem: "No module named 'pkg_resources'"

This error means the setuptools package is missing. Install it with pip:

 pip install setuptools 

Problem: isort and Black keep overwriting each other

This happens when the Black profile is not set. Add profile = "black" to your isort configuration file. Both tools will then produce compatible output.

Problem: isort is not sorting imports in a specific file

Check if the file is in isort's skip list. By default, isort skips directories like .git, venv, and build. You can override this with the --skip flag or by editing your config file.

Problem: GitHub Actions fails to install isort

Some CI runners require a virtual environment for Python packages. Add a step to create and activate a virtual environment before installing isort.

If you plan to generate PDF reports from your Python pipeline, you might pair isort with a library like ReportLab to create PDFs programmatically. Clean imports make that integration smoother.

Best Practices for isort

Follow these tips to get the most out of isort in your projects.

1. Always use a configuration file. A pyproject.toml or .isort.cfg file keeps settings consistent across your team. Everyone gets the same import order without manual setup.

2. Run isort before Black. When using both tools, run isort first. It sorts imports, then Black formats the rest of the code. This order prevents conflicts.

3. Add isort to CI. Run isort --check --diff . in your continuous integration pipeline. This fails the build if imports are not sorted, catching issues before they merge.

4. Use the --atomic flag for safety. The --atomic flag only applies changes if they do not introduce syntax errors. This protects you from accidentally breaking a file.

5. Keep isort updated. New versions add support for new Python features and fix bugs. Run pip install --upgrade isort regularly to stay current.

Frequently Asked Questions

Does isort work with Python 2 code?

Yes. isort supports formatting Python 2 code even though it runs on Python 3.10 and above.

Can I use isort without a virtual environment?

Yes. You can install isort globally with pip install isort. But virtual environments are recommended to avoid dependency conflicts.

How do I skip a specific file or directory?

Use the --skip flag or add a skip option to your config file. For example: skip = migrations.

Does isort remove unused imports?

No. isort only sorts and organizes imports. It does not detect unused imports. Use a linter like flake8 or ruff for that purpose.

Can I customize the import sections?

Yes. The sections and forced_separate options let you define custom import groups. This is useful for monorepos with multiple local packages.

Conclusion

Installing isort in Python is quick and straightforward. Run pip install isort and you are ready to sort imports in seconds.

The real value comes from configuration and integration. Set the Black profile in your pyproject.toml file. Add isort to your pre-commit hooks. Run it in your CI pipeline.

These steps keep your imports clean across every project. Your team spends less time reviewing import changes and more time building features. That is a win for everyone.

Start with a simple installation today. Add configuration as your project grows. isort scales with you from a single script to a large codebase.