# Windows setup

Complete this setup before class if you can. You need an internet connection, permission to install software for your Windows account, and about 10 GB of free space. These directions use **PowerShell**, the command window built into Windows.

## 1. Open PowerShell

Open the **Start** menu, type `PowerShell`, and choose **Windows PowerShell** or **PowerShell**. A window with a prompt such as `PS C:\Users\YourName>` appears. The prompt shows the folder where a command will run. Type only the commands shown after the prompt, then press **Enter**.

Do not choose “Run as administrator.” If your organization blocks PowerShell scripts or software installation, stop and ask its support staff or the workshop instructor for the prepared classroom computer route.

## 2. Install uv

`uv` installs the correct Python version and all packages recorded for this workshop. Copy this command from the [official uv installation page](https://docs.astral.sh/uv/getting-started/installation/), paste it into PowerShell, and press **Enter**:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

The command temporarily permits the downloaded installer to run. `irm` retrieves the official installer and `iex` runs it. If you are not permitted to run downloaded scripts, do not weaken a managed-machine policy; use the instructor’s fallback.

Close PowerShell, reopen it, and verify the installation:

```powershell
uv --version
```

Success looks like `uv 0.x.y` (the numbers may differ). If PowerShell says that `uv` is not recognized, close every PowerShell window and try once more, then see [troubleshooting](troubleshooting.md).

## 3. Download and extract the workshop folder

Download the workshop ZIP supplied by your instructor or from the repository’s **Code → Download ZIP** button. In File Explorer, open **Downloads**, right-click the ZIP, choose **Extract All…**, and select a short location such as `C:\Users\YourName\Documents`. Click **Extract**.

Open the extracted folder. It must directly contain `README.md`, `pyproject.toml`, `uv.lock`, `notebooks`, and `scripts`. GitHub ZIPs often add a suffix, so the actual folder may be named `napari-workshop-main`; that is fine.

## 4. Move PowerShell into the folder

In File Explorer, click the folder’s address bar, type `powershell`, and press **Enter**. A new PowerShell window opens in that folder. Verify the contents:

```powershell
Get-ChildItem
```

You should see `pyproject.toml`, `uv.lock`, and the `notebooks` and `scripts` folders. If you do not, you may be one folder too high or inside an extra nested ZIP folder.

You can also change folders explicitly. Quotation marks keep paths containing spaces together:

```powershell
cd "$HOME\Documents\napari-workshop-main"
```

## 5. Create the workshop environment

Run:

```powershell
uv sync --locked
```

`uv sync` creates a private `.venv` environment inside this workshop folder and installs its packages. `--locked` requires the tested dependency record in `uv.lock` instead of silently choosing newer versions. uv may download Python 3.12 first. The initial run can take several minutes; later runs are usually faster.

Success ends without red error text and leaves a hidden `.venv` folder. You do not need to activate it. Keep `.venv` in the extracted workshop folder.

Register the environment as a Jupyter kernel:

```powershell
uv run python -m ipykernel install --user --name napari-workshop --display-name "Python (napari workshop)"
```

This runs Python from `.venv` and creates the human-readable kernel choice **Python (napari workshop)**. Success includes a message beginning `Installed kernelspec`.

## 6. Download the teaching data

Follow [Download the data](download-data.md). The recommended command is:

```powershell
uv run scripts/download_data.py --dataset teaching
```

## 7. Check the setup

First run the command-line checks:

```powershell
uv run python scripts/check_setup.py
```

Success lists a Python executable inside this workshop’s `.venv`, napari 0.6.6 and other package versions, available RAM, and `Checks complete`. The exact folder and RAM number vary by computer.

Then test a tiny napari window:

```powershell
uv run python scripts/check_setup.py --gui
```

A separate napari window should appear. Close it after the test. Add `--movie` only when the instructor asks you to test movie export.

## 8. Start JupyterLab

```powershell
uv run jupyter lab
```

PowerShell prints messages and opens JupyterLab in your web browser. Leave PowerShell running. In the browser, double-click `notebooks`, then `00_check_setup.ipynb`. At the upper right, select **Python (napari workshop)**. Use **Run → Run All Cells** and compare each result with the explanation in the notebook.

The notebook runs in the browser, while napari opens as a separate desktop window. Look behind the browser or use **Alt+Tab** if the viewer is hidden.

To finish, save the notebook with **File → Save Notebook**, close the napari window, and in JupyterLab choose **File → Shut Down**. Close PowerShell after the command has stopped. To return on another day, open PowerShell in the workshop folder and run `uv run jupyter lab` again.

> These directions have not yet been certified by a completed Windows platform pilot. Report your Windows version, processor type, and exact error text if a step fails.