00 Setup and pre-course

Get Pixi, Git and a GitHub account working before the hands-on lessons

Install Pixi (and through it everything else), set up Git and GitHub, and check that your laptop is ready. Windows users work in WSL2. GitHub Codespaces is the fallback.
  • Time: 30 to 60 minutes, at home, before the first hands-on lesson (lesson 02).
  • You need: a laptop (macOS, Linux or Windows 10/11) with 10 GB free disk space, and an internet connection.
  • You will have: Pixi, Git and a GitHub account, and a cache of the software we use in class.

Overview

In this course almost all software comes from one tool, Pixi. You install Pixi once; Pixi then installs Python, Quarto, Jupyter, the bioinformatics tools, Snakemake and Nextflow inside each project, at the exact versions the project asks for. That is the main idea of the course in one sentence: the project, not your laptop, decides which software it runs with.

Learning outcome. After this page you can install Pixi on your own computer and use it to run a program you never installed (pixi exec). The setup check at the end proves it.

Choose your setup

Your computer What you do
macOS (Apple silicon or Intel) Work in the Terminal app. Follow the macOS / Linux tabs.
Linux Work in your terminal. Follow the macOS / Linux tabs.
Windows 10 or 11 Install WSL2 with Ubuntu (step 1), then work in the Ubuntu terminal and follow the macOS / Linux tabs.
Nothing works, or a locked-down computer Use GitHub Codespaces in the browser (step 7).

Why WSL2 on Windows? Several tools we use (bwa, samtools, bcftools) are not built for Windows at all. We checked on 2026-10-24: conda-forge and bioconda have Linux and macOS builds of these tools, but no Windows (win-64) builds. Inside WSL2 your laptop runs a real Linux, so everything works.

1. Windows only: install WSL2

Open PowerShell as Administrator (right-click, “Run as administrator”) and run:

wsl --install -d Ubuntu

Restart when asked. Ubuntu then opens and asks you to choose a Linux user name and password (they do not need to match your Windows ones). From now on, open “Ubuntu” from the Start menu whenever this course says “terminal”, and follow the macOS / Linux instructions.

Tip

Keep your course files inside Linux (for example ~/cbio7501), not under /mnt/c/...: it is much faster. To see your Linux files in Windows Explorer, run explorer.exe . in the Ubuntu terminal.

Microsoft’s guide: https://learn.microsoft.com/windows/wsl/install.

2. Open a terminal

  • macOS: Applications → Utilities → Terminal.
  • Linux: your terminal application.
  • Windows: the Ubuntu (WSL2) app from step 1.

Check which shell you have; the answer is usually bash or zsh:

echo "$SHELL"

New to the terminal? Bash 101 is an hour of practice with the commands the lessons use. Do it before lesson 02.

3. Install Pixi

curl -fsSL https://pixi.sh/install.sh | sh

The installer puts pixi in ~/.pixi/bin and adds that folder to your PATH in ~/.bashrc or ~/.zshrc. Close the terminal and open a new one so the change takes effect.

You do not need this if you work in WSL2. For completeness:

powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex"

Check that it works:

pixi --version

Expected output (your version can be newer):

pixi 0.83.0
NoteTelemetry: what the installer sends

The install script sends one anonymous “installation ping” to prefix.dev, the company behind Pixi. To opt out, set PIXI_NO_TELEMETRY=1 before installing: curl -fsSL https://pixi.sh/install.sh | PIXI_NO_TELEMETRY=1 sh. Details: https://pixi.sh/latest/reference/telemetry/.

NoteAlready have Pixi?

Update it with pixi self-update. Anything from version 0.60 on works with this course; we test with 0.83.0.

Optional: tab completion

Tab completion saves typing. Add one line to your shell’s start-up file, then open a new terminal:

echo 'eval "$(pixi completion --shell bash)"' >> ~/.bashrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
echo 'eval "$(pixi completion --shell zsh)"' >> ~/.zshrc

4. Run software you never installed

This is the first taste of Pixi. pixi exec downloads a program into a temporary environment and runs it. Nothing is installed on your system:

pixi exec python --version
pixi exec --spec "quarto>=1.9" quarto --version

The first run takes a minute (it downloads packages); the second run of the same command is fast because Pixi keeps a cache.

5. Git and GitHub

Install Git

Check whether you already have Git (version 2.28 or newer):

git --version

If the command is not found, install Git with Pixi. pixi global installs a tool for your user, outside any project:

pixi global install git
Note

On macOS, git --version may offer to install Apple’s “command line developer tools”. Accept, or use pixi global install git instead.

Tell Git who you are

Use the same email address as on GitHub. Replace the example values:

git config --global user.name "Ada Lovelace"
git config --global user.email "ada@example.org"
git config --global init.defaultBranch main
git config --global core.editor nano

The third line makes new repositories start on a branch called main, as on GitHub. The last one makes Git open nano, an easy editor, when it needs a message from you; otherwise it often opens vim, which is hard to leave the first time (Terminal editors and sessions).

The email is written into every commit, and anyone can read it once you push to a public repository. To keep your address private, use the noreply address that GitHub shows under Settings → Emails (it looks like 12345678+ada-lovelace@users.noreply.github.com).

Create a GitHub account and an SSH key

  1. Create a free account at https://github.com/signup if you do not have one. As a student you can also ask for the free GitHub Education benefits.
  2. GitHub needs a key, not a password, when you upload from the terminal. Follow GitHub’s two short guides: generate an SSH key and add it to your account.
  3. Test the connection. The answer should greet you by your user name:
ssh -T git@github.com

6. Docker (needed for lesson 08)

Install Docker before lesson 08:

Check it:

docker run --rm hello-world

A free Docker Hub account is optional; in lesson 08 we push images to the GitHub Container Registry with your GitHub account.

7. The fallback: GitHub Codespaces

If installing fails, or your computer does not let you install software, use a Codespace: a Linux computer in the browser with Pixi already installed.

  1. Open https://github.com/khan-lab/cbio7501-f26.
  2. Click Code → Codespaces → Create codespace on main.
  3. Wait a few minutes the first time. You get VS Code in the browser with a terminal at the bottom.
WarningCodespaces is free only up to a monthly quota

On 2026-10-24 GitHub’s billing page listed, for free personal accounts, 120 core-hours of compute and 15 GB-month of storage per month (GitHub Pro: 180 core-hours, 20 GB-month). Our codespace uses a 2-core machine, so that is about 60 hours a month. Stop your codespace when you are done (it stops by itself after 30 minutes idle), and delete old ones at https://github.com/codespaces. Without a payment method on file, GitHub blocks use once the quota is used up; it resets each month.

8. Fill the cache before class

Classroom Wi-Fi gets slow when 30 laptops download the same 2 GB at once. Run this at home: it downloads the main tools of the course into Pixi’s cache (it runs samtools once to show it worked).

pixi exec -c conda-forge -c bioconda \
  --spec fastqc --spec multiqc --spec bwa --spec samtools --spec bcftools \
  -- samtools --version

Expected output starts with:

samtools 1.24
Using htslib 1.24

On native Windows (not WSL2) this command fails: there are no Windows builds of these tools. That is expected; use WSL2.

9. Setup check

Run the check and keep the output; your instructor may ask for it.

echo "== setup check $(date +%F)"
uname -sm
pixi --version
pixi exec python --version
pixi exec --spec "quarto>=1.9" quarto --version
git --version

Try it yourself

  1. Run pixi exec cowpy "Hello from Pixi". Which package did Pixi download, and did it install anything on your system?

    Pixi guessed the package cowpy from the command name, downloaded it (and Python) into a temporary environment in its cache, and ran it. Nothing was added to your PATH; the next time you type cowpy without pixi exec, it is not found.

  2. Run pixi info. Where is Pixi’s cache on your computer, and how big might it get?

    The line Cache dir shows it (on macOS ~/Library/Caches/rattler/cache, on Linux ~/.cache/rattler/cache). It grows with every package version you use, easily to several GB. pixi clean cache empties it (see Take-down).

Break it: what “command not found” means

Your shell finds programs by looking in the folders listed in PATH. Run pixi with a PATH that does not contain Pixi’s folder:

env PATH=/usr/bin:/bin pixi --version
env: pixi: No such file or directory

Nothing is broken: Pixi is still installed, the shell just does not look in ~/.pixi/bin. This is why the installer asks you to open a new terminal, and why pixi run matters later: it puts the project’s tools on PATH for one command only.

Troubleshooting

Problem What to do
pixi: command not found right after installing Open a new terminal. If it persists, add export PATH="$HOME/.pixi/bin:$PATH" to ~/.bashrc or ~/.zshrc.
curl: (6) Could not resolve host in WSL2 WSL2 lost its DNS settings. Restart WSL with wsl --shutdown in PowerShell and open Ubuntu again. If it persists, ask in class.
Downloads time out or are very slow Try again later or from another network; for a whole class, use the prefetch in step 8 at home. University proxies may need https_proxy set.
First run of anything on macOS is slow macOS scans new programs once. Optional: System Settings → Privacy & Security → Developer Tools, add your terminal app.
No space left on device Free space or empty Pixi’s cache with pixi clean cache.
samtools fails on Windows Expected: no Windows builds. Use WSL2 or Codespaces.
Codespace does not start: quota used Wait for the monthly reset, use WSL2, or ask the instructor for the lab machines.

Key points

  • Install Pixi once; projects install everything else through it.
  • pixi exec runs a tool from a temporary environment without installing it.
  • Windows users work in WSL2 (Linux), because key tools have no Windows builds.
  • Codespaces is the fallback, within a monthly free quota.
  • “Command not found” means “not on PATH”, not “broken”.

Further reading