Skip to content
Back to top
View this page

# File collection and discovery

You can directly pass Black files, but you can also pass directories and Black will walk them, collecting files to format. It determines what files to format or skip automatically using the inclusion and exclusion regexes and as well their modification time.

## Ignoring unmodified files

Black remembers files it has already formatted, unless the `--diff` flag is used or code is passed via standard input. This information is stored per-user. The exact location of the file depends on the Black version and the system on which Black is run. The file is non-portable. The standard location on common operating systems is:

- Windows: `C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.<file-mode>.pickle`

- macOS: `/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.<file-mode>.pickle`

- Linux: `/home/<username>/.cache/black/<version>/cache.<line-length>.<file-mode>.pickle`

`file-mode` is an int flag that determines whether the file was formatted as 3.6+ only, as .pyi, and whether string normalization was omitted.

To override the location of these files on all systems, set the environment variable `BLACK_CACHE_DIR` to the preferred location. Alternatively on macOS and Linux, set `XDG_CACHE_HOME` to your preferred location. For example, if you want to put the cache in the directory you’re running Black from, set `BLACK_CACHE_DIR=.cache/black`. Black will then write the above files to `.cache/black`. Note that `BLACK_CACHE_DIR` will take precedence over `XDG_CACHE_HOME` if both are set.

### Disabling the cache with –no-cache

If you need Black to always perform a fresh analysis and not consult or update the on-disk cache, use the `--no-cache` flag. When provided, Black will neither read from nor write to the per-user cache. This is useful for debugging, for CI runs where you want a deterministic fresh run, or when you suspect cache corruption.

Example:

python -m black –no-cache .

## .gitignore

If `--exclude` is not set, Black will automatically ignore files and directories in `.gitignore` file(s), if present.

If you want Black to continue using `.gitignore` while also configuring the exclusion rules, please use `--extend-exclude`.