Part 1

Author

Affiliation

Elgin Akin

Johns Hopkins University

Modified

October 8, 2026

Navigate back to the blog post

Important

The Docker runtime is no longer supported. Earlier versions of this tutorial used Docker Desktop and nextstrain shell. The pipeline now runs from a single conda environment, pekosz-nextstrain, built by scripts/build_env.sh. Viewing trees locally under Docker was unreliable (especially on WSL), and the Docker image may not include the packages the surveillance report needs. If you set up with Docker before, you do not need to uninstall it, but follow the steps below instead of nextstrain shell.

Warning

Important note about GISAID data

GISAID data cannot be openly redistributed. For that reason, vaccine.fasta is not included in this tutorial.

You must obtain an authorized vaccine FASTA using your own GISAID account and place it at exactly:

tutorial/vaccine.fasta

Do not commit or publicly share this file. The FASTA headers must use the seven-field format described in Tutorial 3: Updating Vaccine Strains on the project wiki.

The project wiki is the authoritative documentation. This page follows its Getting Started and Tutorial 1: Your First Build pages.

What you need

The pipeline runs on macOS (Apple Silicon or Intel) and on Windows through WSL2. Before beginning, you need:

a terminal: Terminal on macOS; on Windows, the Ubuntu terminal of WSL2
git (preinstalled on macOS; sudo apt install git on WSL)
conda, installed through Miniforge (step 1)
an internet connection (the build downloads current Nextclade datasets)
optionally, Positron as an editor, with the Snakemake Language and SQLite Viewer extensions
an authorized vaccine.fasta from GISAID (or an empty placeholder, step 5)

Setup takes about 20 minutes, mostly waiting. The tutorial run itself takes a few minutes.

1. Install Miniforge (conda)

Miniforge provides conda, configured for the conda-forge channel (no Anaconda licence needed).

macOS

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Windows (WSL2): install WSL2 from an administrator PowerShell with wsl --install, restart, open Ubuntu from the Start menu, then run the same two commands in the Ubuntu terminal.

Accept the licence and the default location, and answer yes when asked to initialise conda. Close the terminal and open a new one: your prompt now starts with (base).

An existing Anaconda or Miniconda installation also works (conda 23.10 or newer).

2. Clone the repository

git clone https://github.com/Pekosz-Lab/nextstrain.git
cd nextstrain

All remaining commands must be run from this top-level nextstrain folder, the one containing Snakefile, config/ and tutorial/.

If you use Positron, select File > Open Folder, open the top-level nextstrain folder (not the tutorial subfolder), then open a terminal with Terminal > New Terminal.

Note

On WSL, clone into your Linux home (cd ~ first), not under /mnt/c/.... Builds on the Windows drive are many times slower and can fail on file permissions. Cloud-synced folders (OneDrive, Dropbox) work, but the sync client copies restricted data to the cloud and can interfere with git; keep your clone outside synced folders if you can.

3. Build the environment

bash scripts/build_env.sh

This one command:

creates (or updates) the pekosz-nextstrain conda environment from workflow/envs/environment.yml;
turns on the data-protection git hooks for your clone and creates the empty source_prep/runs/ and source_prep/output/ folders used in Part 2; and
checks every tool (Snakemake, augur, Nextclade, MAFFT, IQ-TREE, seqkit, BLAST, csvtk) and runs small alignment, tree, BLAST and report tests.

Wait for All N checks passed.

Situation	Command
Update after `environment.yml` changes	`bash scripts/build_env.sh`
Rebuild from scratch	`bash scripts/build_env.sh --recreate`
Apple Silicon solve fails	`bash scripts/build_env.sh --intel`
Re-run the checks only	`bash scripts/build_env.sh --check`
All options	`bash scripts/build_env.sh --help`

4. Activate the environment and check your setup

Activate the environment in every new terminal:

conda activate pekosz-nextstrain

Your prompt now shows (pekosz-nextstrain). Confirm the setup:

git config --get core.hooksPath     # must print .githooks
snakemake --version                 # prints a 9.x version

Confirm you are in the right folder:

ls Snakefile config/tutorial.yaml tutorial/JHH_sequences.fasta

Never pip install or conda install into pekosz-nextstrain by hand; your environment would silently differ from everyone else’s.

5. Supply the GISAID vaccine file

After downloading and formatting your authorized vaccine sequences (Tutorial 3), save the file as:

tutorial/vaccine.fasta

No GISAID account yet? The pipeline runs fine with an empty file; your trees just won’t show vaccine strains:

touch tutorial/vaccine.fasta

Git ignores this file and the data guard blocks it, but never commit or share it. Confirm all three tutorial inputs are present:

ls -lh \
  tutorial/JHH_sequences.fasta \
  tutorial/JHH_metadata.txt \
  tutorial/vaccine.fasta

6. Check what will run (recommended)

A dry run checks the workflow and input paths without creating the builds:

snakemake --dry-run --cores 8 --configfile config/tutorial.yaml

You’ll see a list of jobs and a summary count. A message mentioning tutorial/vaccine.fasta means the vaccine file is missing or misnamed.

7. Run the tutorial

snakemake --profile profiles/default --cores 8 --configfile config/tutorial.yaml

What the command means:

snakemake starts the workflow.
--profile profiles/default prints each command, prints the log of any failed job, reruns jobs interrupted by a crash, and lets the other builds finish if one fails.
--cores 8 permits up to eight CPU cores. On smaller computers, use --cores 4 or --cores 2.
--configfile config/tutorial.yaml selects the small tutorial inputs in tutorial/ instead of the normal files in source/.

At the start you’ll see a data-protection line (data_guard: OK ...). Successful completion ends without a red error message and creates:

auspice/
├── h1n1/     8 segment builds + genome build (+ tip-frequency files)
├── h3n2/
└── vic/
reports/
├── surveillance_report.html   interactive report – open in any browser
├── surveillance_report.pptx   slide deck
├── figures/  tables/          PNG figures and TSV tables
└── report.tsv  report.xlsx

That is 24 segment builds, 3 whole-genome builds and the surveillance report.

8. Look at what you made

The report: open reports/surveillance_report.html in a browser (macOS: open reports/surveillance_report.html; WSL: explorer.exe reports/surveillance_report.html).
Explore live: marimo run scripts/report.py opens the report as an app where you can pick any sequencing run.
The trees: go to auspice.us and drag in a build’s two JSON files (for example auspice/h3n2/ha.json and auspice/h3n2/ha_tip-frequencies.json), or serve them locally (see below). Try coloring by clade, then by sequencing_run.
How the run went: .run/reports/index.md and the run’s report.md.

auspice view --datasetDir auspice/h3n2     # then open http://localhost:4000

On WSL, open http://localhost:4000 in your normal Windows browser. If the page won’t load, use auspice.us, which needs no local server.

9. Clean up

Before running anything else (another tutorial run or a production build), archive and clean the workspace:

snakemake --cores 8 snapshot_clean

This copies auspice/, .run/, reports/, source/, nextclade/, results/ and config/ into snapshots/{timestamp}.tar.gz, then deletes data/, results/, reports/, auspice/, fludb.db and the run logs. Run history in .run/run_logs/ and .run/reports/ is kept.

Rerunning and troubleshooting

A previous production build exists

Tutorial and production runs share data/, results/, .run/, auspice/, reports/ and fludb.db. Do not mix them: use a fresh clone, or archive first with snapshot_clean (it deletes outputs, so read Step 2 first).

`command not found: snakemake` (or augur, nextclade…)

The environment is not active:

conda activate pekosz-nextstrain

Re-check any time with bash scripts/build_env.sh --check. If the environment is broken or out of date, rebuild it with bash scripts/build_env.sh --recreate.

The workflow was interrupted

Fix the cause and rerun the same command. The default profile includes rerun-incomplete, so Snakemake reuses completed files and continues the remaining work.

The vaccine file is rejected

Check that the file is named exactly tutorial/vaccine.fasta and that every header has the seven-field format. This prints nothing when all headers have seven fields:

grep '^>' tutorial/vaccine.fasta | awk -F'|' 'NF != 7'

Never post GISAID sequence data in a public issue, repository, or support message.

Beyond this tutorial:

Part 2 covers adding real sequencing runs and running a production build: Part 2 Tutorial Slides
The Pekosz Lab Nextstrain wiki (setup, step-by-step guides, tutorials, data protection)
The Pekosz Lab Nextstrain GitHub: https://github.com/Pekosz-Lab/nextstrain
The Pekosz Lab Nextstrain Builds:
- Privately hosted for internal surveillance meetings: https://nextstrain.org/groups/PekoszLab
- Publicly hosted for publications: https://nextstrain.org/groups/PekoszLab-Public