Getting started

Installation

Python 3.10 or higher is required. lintquarto itself has only four required packages: toml, pyyaml, tree-sitter and tree-sitter-markdown.

You can install lintquarto with pip (from PyPI or GitHub) or conda (from conda-forge).

Install with pip

Install lintquarto with:

pip install lintquarto

Linters are installed separately. For example, to use pylint and flake8, run:

pip install pylint flake8

If you want to install lintquarto along with all supported linters, use:

pip install lintquarto[all]

You can verify your installation with:

lintquarto --version

Install with conda

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).

Development version

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 code quality tools 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]"


Basic usage

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.

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 run tools on.
  • -e, --exclude [[exclude_paths] ...] - Files and/or directories to exclude from running tools on.
  • -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.


Configuration file

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 equivalent 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.


Examples

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/ and ignore/, or-
  • Excluding a specific file analysis/test.qmd.
lintquarto -l ruff -p . -e examples ignore
lintquarto -l ruff -p . -e analysis/test.qmd