Registry / data / shandy-sqlfmt

shandy-sqlfmt

library0.29.0pypypiunverified

sqlfmt is an opinionated Python-based command-line tool that automatically formats your dbt SQL files and other SQL statements. Similar to `black` for Python, it enforces a consistent style with minimal configuration, primarily line length. It is currently at version 0.29.0 and maintains an active release cadence with frequent updates.

data testing

pip install shandy-sqlfmt

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · SHANDY-SQLFMT

shandy-sqlfmt

datapythonv0.29.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

sqlfmt is primarily a command-line tool. The most common usage is to format files in a directory. It will exit with a non-zero code if files are not formatted when using `--check` or `--diff`.

# To format all .sql and .sql.jinja files in the current directory and subdirectories: sqlfmt . # To see a diff of changes sqlfmt would make (without modifying files): sqlfmt --diff . # To format SQL from stdin and print to stdout: echo "select 1,2,3 from my_table where a=1" | sqlfmt -

sqlfmt --version

Debug

Known issues

breakingsqlfmt now requires Python 3.10 or newer. Users on older Python versions will need to upgrade their environment.

fix

Upgrade your Python environment to version 3.10 or higher. For example, using pyenv or updating your system Python.

affects: 0.29.0+

gotchasqlfmt is an alpha product and might not always produce the desired formatted output, or could potentially break SQL syntax. It is strongly recommended to run it on files in a version control system and commit changes before running sqlfmt.

fix

Always use sqlfmt within a version-controlled project (e.g., Git) and commit your changes before running the formatter. Review the diffs carefully before accepting them.

affects: All versions

breakingWhen writing formatted code to stdout, sqlfmt no longer includes an extra trailing newline. This may affect scripts or tools that expect an additional newline when piping `sqlfmt` output.

fix

Adjust any scripts or processes that consume `sqlfmt`'s stdout to account for the absence of the previously included extra trailing newline.

affects: 0.29.0+

gotchasqlfmt is opinionated and not configurable beyond line length. It enforces a single style. If you require highly customizable formatting rules, sqlfmt may not be suitable.

fix

Understand that `sqlfmt` prioritizes consistency over customization. If its style does not align with your needs, consider alternatives or adapt your team to the `sqlfmt` style.

affects: All versions

Errors

Common errors & fixes

sqlfmt: command not found

The `sqlfmt` executable is not in the system's PATH, typically because pip installed it to a user-specific binary directory or it was installed in an inactive virtual environment.

fix

Activate your virtual environment if you used one for installation. Alternatively, ensure the directory containing the `sqlfmt` executable (e.g., `~/.local/bin` on Linux/macOS or `C:\Users\YourUser\AppData\Roaming\Python\Scripts` on Windows) is in your system's PATH, or run it using `python -m sqlfmt`.

sqlfmt.parser.ParseError: Expected

The SQL file contains syntax that `sqlfmt`'s parser does not understand or expects a different token at a specific position, often due to complex or non-standard SQL, or issues with Jinja templating.

fix

Simplify the SQL statement causing the error or adjust it to be more standard. If using dbt/Jinja, try to isolate the problematic part or use `{# sqlfmt: off #}` and `{# sqlfmt: on #}` comments to exclude specific blocks from formatting. Ensure your `shandy-sqlfmt` version is up-to-date, as parsing capabilities are frequently improved.

Exiting with code 1 due to unformatted files.

`sqlfmt` was run with the `--check` flag (common in CI/CD pipelines), and one or more SQL files did not conform to the expected format.

fix

Run `sqlfmt .` (or `sqlfmt <target_files>`) without the `--check` flag to automatically format the files, then commit the changes.

Error: No such option: --<some_option>

The user passed an argument or option to `sqlfmt` that is not recognized by the current version of the tool, possibly due to a typo, deprecation, or an option from a different tool.

fix

Consult the `sqlfmt --help` output or the official documentation (on GitHub) for the correct and current command-line options.

Upgrade

Version history

0.29.0latest on PyPI · released Jan 12, 2026

Audit

Dependencies

pythonrequiredRequired for running the tool.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tconbeer/sqlfmt ↗

packagehttps://pypi.org/project/shandy-sqlfmt/ ↗

homepagehttps://sqlfmt.com ↗

docshttps://docs.sqlfmt.com ↗

changeloghttps://github.com/tconbeer/sqlfmt/blob/main/CHANGELOG.md ↗