autoflake

Remove unused variables from a single file and display the diff

$ autoflake --remove-unused-variables [path/to/file.py]

$ autoflake --remove-all-unused-imports [path/to/file1.py path/to/file2.py ...]

$ autoflake --remove-unused-variables --in-place [path/to/file.py]

$ autoflake --remove-unused-variables --in-place --recursive [path/to/directory]

autoflake [OPTIONS] FILE_OR_DIRECTORY...

-i, --in-place
    Edit files in place rather than printing to stdout. This is the most common way to use autoflake to modify files directly.

-r, --recursive
    Search for Python files in subdirectories. Essential for cleaning entire project folders.

--remove-unused-imports
    Remove unused import statements. This is a conservative approach.

--remove-all-unused-imports
    Remove all unused import statements, including those that pyflakes might not flag but are actually unused. This is more aggressive.

--remove-unused-variables
    Remove unused local variables.

--expand-star-imports
    Expand star imports (e.g., from foo import * becomes from foo import bar, baz). Use with caution as it significantly alters code.

--check
    Don't write back, just return status code. Returns 0 if no changes would be made, 1 otherwise. Useful for CI/CD checks.

--diff
    Show diff instead of modifying files.

--exclude
    Exclude files or directories matching the given glob pattern. Can be specified multiple times.

--imports
    Specify extra imports to remove that autoflake might not detect automatically (e.g., os.path).

--exit-zero-if-clean
    Exit with 0 even if files were modified. Useful for pre-commit hooks where a non-zero exit means commit failure.

autoflake is a lightweight, automated code cleaning tool for Python. Its primary function is to intelligently remove unused import statements and unused local variables from Python source files. By parsing the code and leveraging static analysis principles (often based on pyflakes' output for import detection), autoflake helps developers maintain cleaner, more efficient, and readable codebases.

This utility is particularly valuable in large projects or when refactoring, as it automates tedious cleanup tasks that would otherwise require manual effort. It reduces file sizes, prevents potential bugs stemming from stale or misleading imports, and improves code clarity. autoflake can modify files in place, process directories recursively, and offers various options to control its behavior, including aggressive removal of all unused imports, expansion of star imports, and the ability to operate in a 'check-only' mode for CI/CD pipelines. It seamlessly integrates into typical Python development workflows alongside formatters like black and import sorters like isort.

While autoflake is highly effective, it's important to be aware of certain limitations:
- autoflake primarily relies on pyflakes for import detection. If pyflakes doesn't flag an import as unused, autoflake might not remove it (unless --remove-all-unused-imports is used).
- The --remove-all-unused-imports option is aggressive and might remove imports that are used in non-obvious ways (e.g., via eval(), exec(), or introspection), or for their side effects.
- Expanding star imports (--expand-star-imports) can drastically change code readability and potentially introduce naming conflicts if the imported names are common.
- Always use autoflake with version control. Review changes before committing, especially when using options like --in-place or --expand-star-imports.

autoflake is commonly used with pre-commit, a framework for managing and maintaining multi-language pre-commit hooks. Adding autoflake to your .pre-commit-config.yaml ensures that unused imports and variables are automatically removed before every commit, helping to maintain a clean codebase continuously. A typical entry might look like:

```yaml
- repo: https://github.com/PyCQA/autoflake
rev: v2.3.1
hooks:
- id: autoflake
args: ['--in-place', '--remove-all-unused-imports', '--remove-unused-variables', '--ignore-init-module-imports']
```

When used alongside other Python code quality tools, a common workflow is to apply isort first (to sort imports), then autoflake (to remove unused ones), and finally black (to format the code). This order minimizes conflicts and ensures a consistent and clean code style. For example:
isort . && autoflake --in-place --remove-all-unused-imports --remove-unused-variables --recursive . && black .

autoflake was created by myint as a focused tool to address the common problem of stale and unused code in Python projects. Its development stemmed from the need for a simple, yet effective, automatic solution for code cleanup, distinguishing itself by specializing in import and variable removal. It has since become a popular choice for integrating into automated workflows, particularly within pre-commit hooks and CI/CD pipelines, due to its speed and narrow scope. The tool's design reflects a philosophy of doing one thing well, making it a valuable complement to broader linters and formatters in the Python ecosystem.

pyflakes(1), isort(1), black(1), flake8(1)