This repository provides formatting for Snakemake files. It follows the design and specifications of Black.
Warning
snakefmt modifies files in-place by default, thus we strongly
recommend ensuring your files are under version control before doing any formatting.
You can also pipe the file in from stdin, which will print it to the screen, or use the
--diff or --check options. See Usage for more details.
pip install snakefmt
conda install -c bioconda snakefmtAs snakefmt has a Conda recipe, there is a matching image built for each version by
Biocontainers.
In the following examples, all tags (<tag>) can be found
here.
$ docker run -it "quay.io/biocontainers/snakefmt:<tag>" snakefmt --help$ singularity exec "docker://quay.io/biocontainers/snakefmt:<tag>" snakefmt --helpThese instructions include installing uv.
# install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/snakemake/snakefmt && cd snakefmt
# install snakefmt in a new environment
make install
# you can now run snakefmt with
uv run snakefmt --helpInput
from snakemake.utils import min_version
min_version("5.14.0")
configfile: "config.yaml" # snakemake keywords are treated like classes i.e. 2 newlines
SAMPLES = ['s1', 's2'] # strings are normalised
CONDITIONS = ["a", "b", "longlonglonglonglonglonglonglonglonglonglonglonglonglonglonglong"] # long lines are wrapped
include: "rules/foo.smk" # 2 newlines
rule all:
input: "data/results.txt" # newlines after keywords enforced and trailing comma
rule gets_separated_by_two_newlines:
input:
files = expand("long/string/to/data/files/gets_broken_by_black/{sample}.{condition}",sample=SAMPLES, condition=CONDITIONS)
if True:
rule can_be_inside_python_code:
input: "parameters", "get_indented"
threads: 4 # Numeric params stay unindented
params: key_val = "PEP8_formatted"
run:
print("weirdly_spaced_string_gets_respaced")Output
from snakemake.utils import min_version
min_version("5.14.0")
configfile: "config.yaml" # snakemake keywords are treated like classes i.e. 2 newlines
SAMPLES = ["s1", "s2"] # strings are normalised
CONDITIONS = [
"a",
"b",
"longlonglonglonglonglonglonglonglonglonglonglonglonglonglonglong",
] # long lines are wrapped
include: "rules/foo.smk" # 2 newlines
rule all:
input:
"data/results.txt", # newlines after keywords enforced and trailing comma
rule gets_separated_by_two_newlines:
input:
files=expand(
"long/string/to/data/files/gets_broken_by_black/{sample}.{condition}",
sample=SAMPLES,
condition=CONDITIONS,
),
if True:
rule can_be_inside_python_code:
input:
"parameters",
"get_indented",
threads: 4 # Numeric params stay unindented
params:
key_val="PEP8_formatted",
run:
print("weirdly_spaced_string_gets_respaced")Format a single Snakefile.
snakefmt SnakefileFormat all Snakefiles within a directory.
snakefmt workflows/Format a file but write the output to stdout.
snakefmt - < Snakefile$ snakefmt --help
Usage: snakefmt [OPTIONS] [SRC]...
The uncompromising Snakemake code formatter.
SRC specifies directories and files to format. Directories will be searched
for file names that conform to the include/exclude patterns provided.
Files are modified in-place by default; use diff, check, or `snakefmt - <
Snakefile` to avoid this.
Options:
-l, --line-length INT Lines longer than INT will be wrapped. [default:
88]
-s, --sort / -S, --no-sort Sort directives in rules and modules. [default:
sort]
--check Don't write the files back, just return the
status. Return code 0 means nothing would
change. Return code 1 means some files would be
reformatted. Return code 123 means there was an
error.
-d, --diff Don't write the files back, just output a diff
for each file to stdout.
--compact-diff Same as --diff but only shows lines that would
change plus a few lines of context.
--include PATTERN A regular expression that matches files and
directories that should be included on recursive
searches. An empty value means all files are
included regardless of the name. Use forward
slashes for directories on all platforms
(Windows, too). Exclusions are calculated
first, inclusions later. [default:
(\.smk$|^Snakefile)]
--exclude PATTERN A regular expression that matches files and
directories that should be excluded on recursive
searches. An empty value means no paths are
excluded. Use forward slashes for directories on
all platforms (Windows, too). Exclusions are
calculated first, inclusions later. [default: (
\.snakemake/|\.eggs/|\.git/|\.hg/|\.mypy_cache/|
\.nox/|\.tox/|\.venv/|\.svn/|_build/|buck-
out/|/build/|/dist/|\.template/)]
-c, --config PATH Read configuration from PATH. By default, will
try to read from `./pyproject.toml`
-h, --help Show this message and exit.
-V, --version Show the version and exit.
-v, --verbose Turns on debug-level logger.
snakefmt is able to read project-specific default values for its command line options
from a pyproject.toml file. In addition, it will also load any black
configurations you have in the same file.
By default, snakefmt will search in the parent directories of the formatted file(s)
for a file called pyproject.toml and use any configuration there.
If your configuration file is located somewhere else or called something different,
specify it using --config.
Any options you pass on the command line will take precedence over default values in the configuration file.
By default, snakefmt sorts rule directives (like input, output, shell, etc.) into a consistent order. This makes rules easier to read and allows for quicker cross-referencing between inputs, outputs, and the resources used by the execution command.
Directives are grouped by their functional role in the following order:
- Identity & Early Control:
name,default_target - I/O Contract:
input,output,log,benchmark - Wildcard & Path Qualification:
wildcard_constraints,pathvars - Scheduling & Control:
priority,retries,group,localrule,cache,handover - Execution Environment:
shadow,conda,container,singularity,containerized,envmodules - Execution Resources & Parameters:
threads,resources,params - Annotation / Runtime Display:
message - Action:
shell,run,script,notebook,wrapper,cwl,template_engine
This ordering ensures that the directives most frequently used in execution blocks (like threads, resources, and params) are placed immediately above the action directive.
You can disable this feature using the --no-sort flag.
pyproject.toml
[tool.snakefmt]
line_length = 90
include = '\.smk$|^Snakefile|\.py$'
# snakefmt passes these options on to black
[tool.black]
skip_string_normalization = trueIn this example we increase the --line-length value and also include python (*.py)
files for formatting - this effectively runs black on them. snakefmt will also pass
on the [tool.black] settings, internally, to black.
For instructions on how to integrate snakefmt into your editor of choice, refer to
docs/editor_integration.md
snakefmt supports pre-commit, a framework for managing git pre-commit hooks. Using this framework you can run snakefmt whenever you commit a Snakefile or *.smk file. Pre-commit automatically creates an isolated virtual environment with snakefmt and will stop the commit if snakefmt would modify the file. You then review, stage, and re-commit these changes. Pre-commit is especially useful if you don't have access to a CI/CD system like GitHub actions.
To do so, create the file .pre-commit-config.yaml in the root of your project directory with the following:
repos:
- repo: https://github.com/snakemake/snakefmt
rev: v0.10.2 # Replace by any tag/version ≥v0.6.0 : https://github.com/snakemake/snakefmt/releases
hooks:
- id: snakefmtThen install pre-commit and initialize the pre-commit hooks by running pre-commit install (Note you need to run this step once per clone of your repository). Additional pre-commit hooks can be found here.
GitHub Actions in combination with super-linter allows you to automatically run snakefmt on all Snakefiles in your repository e.g. whenever you push a new commit.
To do so, create the file .github/workflows/linter.yml in your repository:
---
name: Lint
on: # yamllint disable-line rule:truthy
push: null
pull_request: null
permissions: {}
jobs:
build:
name: Lint
runs-on: ubuntu-latest
permissions:
contents: read
packages: read
# To report GitHub Actions status checks
statuses: write
steps:
- name: Checkout code
uses: actions/checkout@v5
with:
# super-linter needs the full git history to get the
# list of files that changed across commits
fetch-depth: 0
persist-credentials: false
- name: Lint Code Base
uses: super-linter/super-linter@v8.2.1
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: main
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
VALIDATE_SNAKEMAKE_SNAKEFMT: trueAdditional configuration parameters can be specified by creating .github/linters/.snakefmt.toml:
[tool.black]
skip_string_normalization = trueFor more information check the super-linter readme.
If you can't get enough of badges, then feel free to show others you're using snakefmt
in your project.
[](https://github.com/snakemake/snakefmt).. image:: https://img.shields.io/badge/code%20style-snakefmt-000000.svg
:target: https://github.com/snakemake/snakefmtSee CHANGELOG.md.
See CONTRIBUTING.md.
@article{snakemake2021,
doi = {10.12688/f1000research.29032.2},
url = {https://doi.org/10.12688/f1000research.29032.2},
year = {2021},
month = apr,
publisher = {F1000 Research Ltd},
volume = {10},
pages = {33},
author = {Felix M\"{o}lder and Kim Philipp Jablonski and Brice Letcher and Michael B. Hall and Christopher H. Tomkins-Tinch and Vanessa Sochat and Jan Forster and Soohyun Lee and Sven O. Twardziok and Alexander Kanitz and Andreas Wilm and Manuel Holtgrewe and Sven Rahmann and Sven Nahnsen and Johannes K\"{o}ster},
title = {Sustainable data analysis with Snakemake},
journal = {F1000Research}
}