Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Less uncompromising Python code formatter

Project description


Package Version Build Status

Less uncompromising Python code formatter.

Gray stands on the shoulders of giants:

  • isort - imports sorting and more
  • pyupgrade - automatically upgrades syntax for newer versions of Python
  • autoflake - remove unused imports and variables
  • add-trailing-comma
  • trim - remove trailing whitespaces
  • unify - unify quotes style
  • fixit - various code formatters on LibCST


        gray myproj/ tests/
        gray --log-level debug --formatters isort,unify ~/app

Less uncompromising Python code formatter.

positional arguments:
  paths                 Paths to format (default: (PosixPath('.'),))

optional arguments:
  -h, --help            show this help message and exit
  --pool-size POOL_SIZE
                        process pool size (default: 8)
  --do-not-detect-venv  Don't try to detect virtualenv (default: False)

Logging options:
  --log-level {debug,info,warning,error,fatal}
  --log-format {stream,color,json,syslog}

Formatters options:
  -f FORMATTERS, --formatters FORMATTERS
                        Enabled formatters separated by comma (default: add-
  --min-python-version MIN_PYTHON_VERSION
                        Minimum python version to support (default: (3, 9))

pyupgrade options:
  --pyupgrade-keep-percent-format PYUPGRADE_KEEP_PERCENT_FORMAT
                        Do not upgrade percent formatted strings to f-strings
                        (default: False)

unify options:
  --unify-quote UNIFY_QUOTE
                        preferred quote (default: ")

isort options:
  --isort-line-length ISORT_LINE_LENGTH
                        isort section (default: 80)
  --isort-virtual-env ISORT_VIRTUAL_ENV
                        virtual env path (default:
  --isort-include-trailing-comma ISORT_INCLUDE_TRAILING_COMMA
                        include a trailing comma on multi line imports
                        (default: 1)
  --isort-lines-after-imports ISORT_LINES_AFTER_IMPORTS
                        empty lines after imports (default: 2)

autoflake options:
  --autoflake-ignore-init-module-imports AUTOFLAKE_IGNORE_INIT_MODULE_IMPORTS
  --autoflake-expand-star-imports AUTOFLAKE_EXPAND_STAR_IMPORTS
  --autoflake-remove-all-unused-imports AUTOFLAKE_REMOVE_ALL_UNUSED_IMPORTS
  --autoflake-remove-duplicate-keys AUTOFLAKE_REMOVE_DUPLICATE_KEYS
  --autoflake-remove-unused-variables AUTOFLAKE_REMOVE_UNUSED_VARIABLES

trim options:
  --trim-leading-newlines TRIM_LEADING_NEWLINES

fixit options:
  --fixit-redundant-fstrings FIXIT_REDUNDANT_FSTRINGS
  --fixit-redundant-lambdas FIXIT_REDUNDANT_LAMBDAS
  --fixit-redundant-list-comprehensions FIXIT_REDUNDANT_LIST_COMPREHENSIONS
  --fixit-to-comprehensions FIXIT_TO_COMPREHENSIONS
  --fixit-to-literals FIXIT_TO_LITERALS
  --fixit-to-fstrings FIXIT_TO_FSTRINGS

Args that start with '--' (eg. --pool-size) can also be set in a config file
(/Users/apple/.gray or /etc/gray.conf or ./gray.conf). Config file syntax
allows: key=value, flag=true, stuff=[a,b,c] (for details, see syntax at If an arg is specified in more than one place, then
commandline values override config file values which override defaults.

Git Hook

You can setup gray formatting before each commit with pre-commit git hook. Add following file to .git/hooks/pre-commit and make it executable with chmod +x .git/hooks/pre-commit.

#!/usr/bin/env python
from gray.hooks import git_pre_commit


If stop_on_modify argument is True, hook will prevent commit if there are any unstaged changes in files you about to commit.

Otherwise, any unstaged changes in this files will be added to the index by the hook.

Config file

Gray is looking for config file in ./gray.conf, /etc/gray.conf or ~/.gray.

Example of grayconf:

formatters = add-trailing-comma,isort,unify
min-python-version = 3.5


  • TODO

Git pre-commit hook

Use pre-commit. Once you have it installed, add this to the .pre-commit-config.yaml in your repository:

  - repo:
    rev: master # Replace by any tag/branch:
      - id: gray

and run pre-commit install.

Using with Sourcetree

Sourcetree may run without gray being available via PATH.


Make sure gray is available via PATH and run open /Applications/ Or better create an Automator workflow with source ~/.bash_profile && open /Applications/ script.




  • isort: keep line breaks before local imports


  • Fix isort imports grouping


  • Bump isort to 5.4.2
  • Use parentheses in multiline imports


  • Add autoflake formatter
  • Add trim formatter


  • Minimum python version option
  • Pyupgrade options
  • Detecting and skipping virtualenv



  • Pre-commit hook
  • Some formating options

0.1.0 (2020-04-06)

  • First release on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for gray, version 0.9.0
Filename, size File type Python version Upload date Hashes
Filename, size gray-0.9.0-py2.py3-none-any.whl (16.5 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size gray-0.9.0.tar.gz (15.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page