Install & Compatibility
Where this runs
tested against v0.38.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 36.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.0s · import 0.000s · 36MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sqruff (CLI tool)
✓ Run 'sqruff <command>' from the terminal
Sqruff is primarily designed and documented as a command-line interface (CLI) tool. While it uses Python bindings (via PyO3) for its PyPI distribution, there is no commonly documented direct Python API for programmatic linting or formatting similar to 'import sqruff' functions found in other Python SQL linters. Users are expected to interact with it via its 'sqruff' executable.
This quickstart demonstrates how to install Sqruff and use its primary command-line interface to lint and format a SQL file. It involves creating a sample SQL file and a `.sqruff` configuration file to specify the SQL dialect.
# Create a SQL file to lint
echo "SELECT col1, col2 FROM my_table;" > bad_sql.sql
# Create a configuration file (e.g., .sqruff)
echo "[sqruff]\ndialect = postgres" > .sqruff
# Run the linter
sqruff lint bad_sql.sql
# Or lint all SQL files in the current directory with the config
sqruff lint .
# Run the formatter
sqruff format bad_sql.sql
sqruff --version
Debug
Known issues
gotchaSqruff is primarily a CLI tool; there is no exposed Python API for direct programmatic linting/formatting (e.g., `sqruff.lint('SELECT 1')`) as of version 0.38.0. Users expecting a Python library for in-application use should reconsider or plan to wrap CLI calls.fixInteract with Sqruff via its command-line interface (e.g., `subprocess.run(['sqruff', 'lint', 'file.sql'])`) or by invoking it as a separate process.
affects: All versions up to 0.38.0
breakingThe underlying Rust library, which Sqruff builds upon, has experienced frequent breaking changes across its development cycle (e.g., 28 breaking releases out of 99). While the Python packaging attempts to stabilize the interface, users should review release notes for significant updates that might affect behavior or require configuration adjustments.fixAlways check the official GitHub releases and documentation for breaking changes before upgrading, especially for significant version bumps. Test new versions in a controlled environment.
affects: Potentially any major/minor version updates (e.g., 0.x.x to 0.y.x where y > x)
gotchaIncorrect or missing dialect configuration can lead to unexpected linting/formatting results or errors. Sqruff needs to know the SQL dialect (e.g., PostgreSQL, BigQuery, ANSI) to correctly parse and apply rules.fixAlways define the `dialect` in a `.sqruff` configuration file in your project root or pass it via the `--dialect` flag (e.g., `sqruff lint --dialect postgres .`).
affects: All versions
Upgrade
Version history
0.38.0latest on PyPI · released Apr 12, 2026
Audit
Dependencies
pythonrequiredRequired for Python bindings and distribution via PyPI.
rustrequiredThe core linter is written in Rust, used for compilation of the Python package.