Package for running linters, formatters, static type checkers and code analysis tools on python code in quarto (.qmd) files.
By default, python code validation tools can't check embedded python code in Quarto files. This package fills that gap, enabling analysts and researchers to run python quality checks within Quarto documents.
Currently supported:
- Linters: pylint, flake8, pydoclint, pyflakes, ruff, vulture, and pycodestyle.
- Static type checkers: basedpyright, mypy, pyright, pyrefly, and pytype.
- Code analysis tools: radon.
- Formatters (alpha): ruff.
This package is featured on awesome-quarto.
This package has been reviewed by PyOpenSci.
You can install lintquarto with pip (from PyPI or GitHub) or conda (from conda-forge).
pip install lintquarto
To include your selection of linters, install them as needed.
For a one-step installation that includes lintquarto and all supported linters and type checkers, use:
pip install lintquarto[all]
uv add lintquarto
Or to include all supported linters and type checkers:
uv add "lintquarto[all]"
conda install conda-forge::lintquarto
With conda, only the main lintquarto tool is installed. If you want to use any linters or type checkers, you must install them separately (either with conda or pip, depending on availability).
To install the latest development version of lintquarto directly from this repository:
pip install git+https://github.com/lintquarto/lintquarto
If you also want all supported linters and type checkers in one step, install from a local clone in editable mode with the all extra:
git clone https://github.com/lintquarto/lintquarto.git
cd lintquarto
pip install -e ".[all]"
Usage:
lintquarto [-h] [-l LINTER [LINTER ...]] [-f FORMATTER [FORMATTER ...]] [-p PATHS [PATHS ...]] [-e [[exclude_paths] ...]] [-n] [-v] [-k] [-c COMMAND] {list} ...
Lint Python code in Quarto (.qmd) files. Configuration can also be provided in pyproject.toml under [tool.lintquarto]. CLI arguments override configuration file. WARNING: Formatter option currently in alpha, with known bugs and further testing required. If you run into any problems, feel free to open a GitHub issue and contribute to code if you'd like to!
Options:
-h, --help- show this help message and exit-l, --linters LINTER [LINTER ...]- Linters to run. Valid options: ['basedpyright', 'flake8', 'mypy', 'pycodestyle', 'pydoclint', 'pyflakes', 'pylint', 'pyright', 'pyrefly', 'pytype', 'radon-cc', 'radon-mi', 'radon-raw', 'radon-hal', 'ruff', 'vulture']-f, --formatters FORMATTER [FORMATTER ...]- Formatter to run. Valid options: ['ruff-format', 'ruff-check-fix'].-p, --paths PATHS [PATHS ...]- Quarto files and/or directories to lint.-e, --exclude [[exclude_paths] ...]- Files and/or directories to exclude from linting.-n, --lint-non-exec- Also lint non-executable Python code chunks-v, --verbose- Verbose output.-k, --keep-temp- Keep temporary .py files after linting.-c, --custom-commands COMMAND- Custom command to run against the generated .py file. Repeat for multiple commands. Example: --custom- commands "mytool"
Commands:
list- List supported linters and whether they are available.
Passing extra arguments directly to linters is not supported.
Only .qmd files are processed.
As an alternative to passing flags on every run, you can declare your settings once in a [tool.lintquarto] section in your pyproject.toml. The arguments are eqvuialent to those used on the command line. For example:
[tool.lintquarto]
linters = [
"ruff",
"pycodestyle",
]
paths = [
"examples/",
"dashboard/index.qmd",
]
lint-non-exec = false
With this in place, you can run lintquarto with no arguments.
Note: CLI flags will always take priority over pyproject.toml. If you supply -l or -p on the command line, those values are used and the corresponding config file values are ignored. exclude and custom-commands are additive - values from both sources are merged together.
The linter used is interchangeable in these examples.
Lint all .qmd files in the current directory (using pylint):
lintquarto -l pylint -p .
Lint several specific files (using pylint and flake8):
lintquarto -l pylint flake8 -p file1.qmd file2.qmd
Keep temporary .py files after linting (with pylint)
lintquarto -l pylint -p . -k
Lint all files in current directory (using ruff):
- Excluding folders
examples/andignore/, or- - Excluding a specific file
analysis/test.qmd.
lintquarto -l ruff -p . -e examples ignore
lintquarto -l ruff -p . -e analysis/test.qmd
Visit our website to find out more and see examples from running with each code validation tool.
Thanks goes to these wonderful people (emoji key):
 Amy Heather 🎨 📖 🤔 🚇 🚧 |
 Isabel Zimmerman 🤔 📖 |
 Jacob Cumming 🐛 📖 🤔 |
 Jonny Saunders 🐛 💻 🤔 |
 Sammi Rosser 💻 📖 |
 Anna Laws 📖 |
 Nissim Lebovits 🤔 |
 Tom Monks 📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!
Curious about contributing? Check out the contributing guidelines to learn how you can help. Every bit of help counts, and your contribution - no matter how minor - is highly valued.
Please cite the repository on GitHub, PyPI, conda and/or Zenodo:
Heather, A. (2026). lintquarto (v0.13.1). https://github.com/lintquarto/lintquarto.
Heather, A. (2026). lintquarto (v0.13.1). https://pypi.org/project/lintquarto/.
Heather, A. (2026). lintquarto (v0.13.1). https://anaconda.org/conda-forge/lintquarto.
Heather, A. (2026). lintquarto (v0.13.1). https://doi.org/10.5281/zenodo.15731161.
Citation instructions are also provided in CITATION.cff.
This project was written and maintained by hand, with occasional use of Perplexity AI during development (specific models and versions varied over time).
AI assistance was used for small, targeted tasks (e.g. help when troubleshooting, identifying issues, refining docstrings, improving code structure), rather than to generate complete functions or substantial content.
All code and design decisions were reviewed and finalised by a human. For transparency, the use of AI is acknowledged, but the project should not be considered AI‑generated.