Setup

Run tutorial for free in the cloud via Gitpod

The easiest way to run this tutorial is to use Gitpod, which enables performing the exercises via your browser—including all required software, for free and in the cloud. In order to do this, simply open the predefined snakemake-tutorial GitPod workspace in your browser. GitPod provides you with a Theia development environment, which you can learn about in the linked documentation. Once you have a basic understanding of this environment, you can go on directly with Basics: An example workflow.

Note

A common thing to happen while using the development environment in GitPod is to hit Ctrl-s while in the terminal window, because you wanted to save a file in the editor window. This will freeze your terminal. To get it back, make sure you selected the terminal window by clicking on it and then hit Ctrl-q.

Running the tutorial on your local machine

If you prefer to run the tutorial on your local machine, please follow the installation instructions for either pixi or miniforge.

The tutorial assumes that you are using either Linux or MacOS. Snakemake, Pixi, and Miniforge work also under Windows, but the Windows shell is too different to be able to provide generic examples.

1. Install Snakemake

Follow the installation instructions using either pixi or miniforge options to install snakemake.

2. Prepare a working directory

Create a new directory snakemake-tutorial at a place you can easily remember and change into that directory in your terminal:

$ mkdir snakemake-tutorial
$ cd snakemake-tutorial

In this directory, we will later create an example workflow that illustrates the Snakemake syntax and execution environment.

Next, we will download some example data on which to run the workflow:

$ curl -L https://api.github.com/repos/snakemake/snakemake-tutorial-data/tarball -o snakemake-tutorial-data.tar.gz

Extract the data:

$ tar --wildcards -xf snakemake-tutorial-data.tar.gz --strip 1 "*/data" "*/environment.yaml"

$ tar -xf snakemake-tutorial-data.tar.gz --strip 1 "*/data" "*/environment.yaml"

This will create a folder data and a file environment.yaml in the working directory.

3. Install Workflow Dependencies

The tutorial provides an environment.yaml file that lists all required software for the workflow.

To import this environment and install all the required software for the tutorial workflow:

$ pixi init --import environment.yaml

$ conda activate base
$ mamba env create --name snakemake-tutorial --file environment.yaml

4. Activate the environment

To activate the snakemake-tutorial environment, execute

$ pixi shell

$ conda activate snakemake-tutorial

Now you can use the installed tools within this shell.

If you want to exit this shell later, use

$ exit

$ conda deactivate

to return to your normal shell. But don’t do that now, since we finally want to start working with Snakemake! :-)