Skip to content

Installation and first check

We will create a separate Python 3 environment, install Snakemake 9, obtain the two example repositories and run a one-rule installation check. Keep this page open while working in the terminal.

Before you begin

These commands use a bash or zsh terminal on Linux or macOS, with Python 3, its venv module and Git already installed. You also need internet access and a writable directory. On Windows, use a Linux environment such as WSL; the native Windows shell is not covered here. For other installation methods, consult the official Snakemake installation guide.

The workshop was prepared using Python 3.12 (tested release: 3.12.15). The commands below therefore use python3.12.

Run:

python3.12 --version
git --version

The first command should report Python 3.12.x; the second should report a Git version. If either command is missing, arrange installation with the instructor or your system administrator before proceeding. On a managed cluster, use its documented software-access procedure rather than installing system software yourself.

This setup covers the introduction and the first workflow example. The scientific analysis will additionally need NumPy, SciPy, Matplotlib, h5py and iminuit; cluster execution will need its own configuration. We will introduce those requirements with the relevant parts of the workshop.

1. Create a working directory and environment

Choose a writable parent directory in your terminal. The following commands create a new directory named snakemake-workshop. If you already have a directory with that name, choose another new name rather than mixing this exercise with previous work.

mkdir snakemake-workshop
cd snakemake-workshop
python3.12 -m venv .venv
source .venv/bin/activate

The .venv directory contains a local Python environment. Activating it makes the shell use its Python and installed commands. Packages installed there are kept separate from other Python environments. See the Python documentation for virtual environments.

Keep the same terminal open for the following steps. All commands below begin in snakemake-workshop unless a cd command changes the directory.

2. Install and check Snakemake

We will install Snakemake 9.27.1, the latest stable release when the workshop was prepared (25 October 2026), listed on PyPI.

python -m pip install "snakemake==9.27.1"
python --version
snakemake --version
python -m pip check

Check that Python reports 3.12.x, Snakemake reports 9.27.1, and the last command reports No broken requirements found. The Snakemake version is pinned so everyone uses the same workflow-engine release. This does not lock every transitive dependency to one version.

If snakemake is not found, check that activation in step 1 succeeded and that the installation command completed without an error. Do not continue to the examples after a failed installation.

3. Obtain the workshop materials

Still in snakemake-workshop, run:

git clone https://github.com/leskovec/SnakeMake.intro.git
git clone https://github.com/leskovec/SnakeMake.main.git
git -C SnakeMake.intro checkout --detach 9080311347064dc48614633c3ddf7f48796d1503
git -C SnakeMake.main checkout --detach 97ae1cac38ea025585709ebe43f2ad9725f2f75f
ls SnakeMake.intro
ls SnakeMake.main

The first listing should include app.py, app_v0.py, script and snakemake. The second should include data, program and program.solution. Leave the original files unchanged for now. The checkout commands select the snapshots used to prepare these lessons. Git may report a detached HEAD; that is expected for these read-only source copies. Record the revisions with:

git -C SnakeMake.intro rev-parse HEAD
git -C SnakeMake.main rev-parse HEAD

The two output hashes identify the revisions you obtained and help explain differences if the repositories change.

4. Run a minimal installation check

We will make a small Snakefile in its own directory. It has one rule, called hello, whose output is hello.txt. The shell command writes one line to that file. We will study rule syntax in the next part; here the purpose is to check that the installation can execute a job.

From snakemake-workshop, copy the complete block below. The final EOF must be on its own line. This shell syntax writes the intervening text into a file named Snakefile.

mkdir installation-check
cd installation-check
cat > Snakefile <<'EOF'
rule hello:
    output:
        "hello.txt"
    shell:
        "printf 'Snakemake is ready\\n' > {output}"
EOF

For this check we explicitly select the built-in greedy scheduler, which avoids requiring an external optimization solver. This is a choice of how Snakemake selects ready jobs, not a cluster scheduler.

First inspect the plan without running the job:

snakemake --cores 1 --scheduler greedy --dry-run

The plan should contain one hello job. A dry run of this small workflow does not create hello.txt. Now execute the job and inspect its output:

snakemake --cores 1 --scheduler greedy
cat hello.txt

The file should contain exactly:

Snakemake is ready

Run the same command once more:

snakemake --cores 1 --scheduler greedy

With the file and workflow unchanged, Snakemake should report that there is nothing to do. We requested one core for this check; this is not a performance test.

5. Return to the workshop directory

cd ..

You are now back in snakemake-workshop, with the environment still active. The resulting layout is:

snakemake-workshop/
├── .venv/
├── SnakeMake.intro/
├── SnakeMake.main/
└── installation-check/
    ├── Snakefile
    ├── hello.txt
    └── .snakemake/     (execution metadata)

When you open a new terminal later, return to this directory and reactivate the environment with source .venv/bin/activate. When you have finished working, deactivate leaves the environment without deleting your work.

You are ready for the first workflow example when the version checks pass, both repositories are present, and the installation check creates the expected line and performs no work on an unchanged rerun. Continue with the introductory exercises.

Optional: environment for the Slurm executor

This step is only needed for mode B in the cluster chapter. You can skip it for now and return when you reach that chapter. Run these commands from snakemake-workshop on the cluster, using its supported Python setup. The Slurm plugin requires a newer NumPy than the scientific example pins, so install it in a separate environment:

python3.12 -m venv .venv-slurm
source .venv-slurm/bin/activate
python -m pip install "snakemake==9.27.1" "snakemake-executor-plugin-slurm==2.8.0"
python -m pip check
source .venv/bin/activate

The final command reactivates the main workshop environment. When you reach the cluster chapter, activate .venv-slurm as shown there. Both environments must be on storage accessible to the compute nodes.