autopep8
Automatically format Python code to conform to PEP 8
TLDR
Format a file to stdout, with a custom maximum line length
Format a file, displaying a diff of the changes
Format a file in-place and save the changes
Recursively format all files in a directory in-place and save changes
SYNOPSIS
autopep8 [options] file_or_directory ...
PARAMETERS
-h, --help
Show a help message and exit.
-i, --in-place
Make changes to files in place. This is often the most used option.
-d, --diff
Show diffs of the changes instead of modifying files directly.
-r, --recursive
Run recursively over directories. Useful for entire projects.
-a, --aggressive
Fix more aggressively. Can be specified multiple times (e.g., -aa) for even more aggressive fixes. Use with caution.
-s SELECT, --select=SELECT
Choose which errors and warnings to fix (e.g., E111,W292). You can find codes from pycodestyle documentation.
-I IGNORE, --ignore=IGNORE
Ignore specified errors and warnings from being fixed (e.g., E501 to ignore line length).
--max-line-length=LENGTH
Set the maximum allowed line length. Overrides the default PEP 8 value (79).
--exit-code
Return a non-zero exit code if changes were made to any files. Useful for CI/CD pipelines.
--list-fixes
List all the fixes that autopep8 can apply, along with their associated PEP 8 error codes.
DESCRIPTION
autopep8 is a command-line utility that automatically formats Python code to conform to the PEP 8 style guide. It leverages the pycodestyle (formerly pep8) tool to identify style violations and then applies fixes for a wide range of common issues directly to the source code. This includes correcting indentation, removing trailing whitespace, adjusting blank lines, and more. While it can modify files in-place, it also offers a dry-run mode to display differences or print corrected code to standard output.
autopep8 is often used by developers to maintain consistent code style across projects, making codebases more readable and easier to maintain. It aims to be idempotent, meaning running it multiple times on the same file should not introduce further changes after the initial fixes are applied. It's particularly useful for quickly cleaning up code written by multiple contributors or legacy code that doesn't adhere to modern style guidelines.
CAVEATS
While autopep8 is effective for many style issues, it does not guarantee full PEP 8 compliance nor perfect code. It works best on syntactically valid Python code. Aggressive fixes (using -a or -aa) can sometimes introduce subtle changes that might require careful review. Always back up your code or use autopep8 in conjunction with a version control system (e.g., Git) to easily review and revert changes.
INTEGRATION WITH IDES AND PRE-COMMIT HOOKS
autopep8 can be integrated into various Integrated Development Environments (IDEs) like VS Code or PyCharm, allowing automatic formatting on save. It is also commonly used as a pre-commit hook in version control systems, ensuring that all committed code adheres to styling standards before it enters the repository. This helps maintain code quality and consistency across a development team.
HISTORY
autopep8 emerged as a solution to automate the tedious process of manually fixing Python style violations reported by the pep8 (now pycodestyle) linter. It was developed to make it easier for developers to adhere to the widely adopted PEP 8 style guide without significant manual effort. Its development aimed to provide a practical tool for code cleanup and consistency, predating the rise of more opinionated formatters like Black, offering a more configurable approach to code styling.
SEE ALSO
pycodestyle(1), flake8(1), black(1), isort(1)