Pyink Python Formatter

25.12.0 · active · verified Thu Apr 16

Pyink is a Python code formatter, forked from Black, that offers slightly different formatting behaviors compared to upstream Black. It is actively maintained and regularly rebased on the latest Black releases to serve as an adoption helper for large monorepos with specific formatting requirements. The current stable version is 25.12.0.

Common errors

```
Error: No such option: --pyink-lines
```
cause The `--pyink-lines` option was removed in Pyink 24.3.0 after being deprecated.

fix Use `--line-ranges` instead. For example, change `pyink --pyink-lines 10-20 my_file.py` to `pyink --line-ranges 10-20 my_file.py`.
```
My code is formatted differently by Pyink than by Black, even when they're supposed to be based on the same version.
```
cause Pyink has intentional formatting divergences from Black, such as handling of imports, class/method spacing, and support for 2-space indentation or majority quote styles.

fix These are expected differences. Consult the Pyink README for a list of these divergences. Utilize Pyink-specific options like `--pyink-indentation 2` or `--pyink-use-majority-quotes` to customize behavior.
```
Jupyter notebooks are not formatted correctly or show unexpected changes when using Pyink.
```
cause Jupyter notebook formatting (especially `ipynb` files) has specific considerations for JSON content indentation and Unicode escaping that require dedicated options.

fix Use Pyink's specific options for notebooks: `--pyink-ipynb-indentation` to control JSON indentation (available from 24.10.0) and `--pyink-ipynb-unicode-escape` for Unicode escaping (available from 24.10.1).

Warnings

breaking The `--pyink-lines` CLI option was deprecated in Pyink 23.12.1 and completely removed in 24.3.0. Using this option in newer versions will result in an error.
Fix: Replace `--pyink-lines START-END` with Black's built-in `--line-ranges START-END` option (e.g., `pyink --line-ranges 10-20 my_file.py`).
gotcha Pyink intentionally implements several formatting differences compared to upstream Black, even when based on the same Black version. Code formatted by Pyink may not be identical to code formatted by Black.
Fix: Review Pyink's README for a full list of divergences, including handling of imports (not wrapped in parentheses), class statement spacing, two-space indentation (`--pyink-indentation`), and majority-based quote style (`--pyink-use-majority-quotes`).
gotcha Pyink 24.10.0 had a dependency to the wrong Black version in its `pyproject.toml`, which was fixed in 24.10.1. This could lead to unexpected formatting behavior or internal inconsistencies.
Fix: Upgrade to Pyink 24.10.1 or a newer version to ensure correct internal Black version alignment.
gotcha Certain Black features, such as Black v23.9.9's concise formatting for dummy implementations, have been temporarily disabled in specific Pyink releases to maintain Pyink's unique formatting style.
Fix: Be aware that specific Black features may be selectively enabled or disabled in Pyink. Refer to the release notes for detailed information on such divergences.

Install

pip install pyink Install Pyink

Quickstart

Pyink is primarily a command-line interface tool. To use it, simply invoke `pyink` followed by the file or directory you wish to format. All Black command-line options are supported, in addition to Pyink-specific options.

# To format a single file:
pyink my_python_script.py

# To format all Python files in the current directory and subdirectories:
pyink .

# To check for formatting issues without applying changes:
pyink --check --diff .

view raw JSON →