---
name: windows-toolchains
description: Install and run Node, Python, .NET, Rust, Java, and Docker toolchains correctly on Windows for coding agents. Use when fixing command-not-found, PATH issues, venv/activation, npm global installs, py launcher, winget/choco/scoop, MSVC build tools, or cross-platform project setup on Windows.
license: MIT
metadata:
  author: javeckbila
  version: "1.0.0"
  platform: windows
---

# Windows toolchains for coding agents

## Package managers (prefer in this order for machines you control)

1. **winget** — built into modern Windows
2. **scoop** — great for dev binaries (user-space)
3. **chocolatey** — common in enterprise (often needs admin)
4. Official installers — when docs require a specific version

```powershell
winget --version
winget search OpenJS.NodeJS
# install only with user approval
# winget install -e --id OpenJS.NodeJS.LTS
```

Do **not** silently install system-wide packages unless the user asks.

## PATH refresh

After installing tools, the current agent shell may not see them:

```powershell
$env:Path = [System.Environment]::GetEnvironmentVariable('Path','Machine') + ';' +
            [System.Environment]::GetEnvironmentVariable('Path','User')
Get-Command node, npm, python, py, dotnet, cargo, java -ErrorAction SilentlyContinue
```

Or open a new shell / restart the agent.

## Node.js

```powershell
node -v
npm -v
# prefer local binaries
npx --no-install tsc -v 2>$null
.\node_modules\.bin\tsc -v
```

- Prefer project-local installs (`npm i`) over global
- On Windows, binaries are `.cmd` shims — call via `npx` or `npm run`
- Avoid assuming `#!/usr/bin/env node` scripts run without `node` or Git Bash

```powershell
npm.cmd run build
# or
npm run build
```

## Python

Prefer the **py launcher**:

```powershell
py -0p                    # list installed
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
```

| Wrong | Right |
|-------|-------|
| `python3` always exists | Often only `py` / `python` on Windows |
| `source .venv/bin/activate` | `.\.venv\Scripts\Activate.ps1` |
| `pip install` system-wide | venv + `python -m pip` |

If activation is blocked by ExecutionPolicy:

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\.venv\Scripts\Activate.ps1
# or run without activate:
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

## .NET

```powershell
dotnet --info
dotnet build
dotnet test
dotnet run --project .\src\App\App.csproj
```

- Use backslash or forward slash in project paths — both usually work
- Solution files: `dotnet build .\MySoln.sln`

## Rust

```powershell
rustup --version
cargo build
```

MSVC toolchain requires **Visual Studio Build Tools** (C++ workload) for many crates. If link errors mention `link.exe`, tell the user — do not silently download multi-GB VS installs without consent.

## Java

```powershell
java -version
where.exe java
```

Prefer explicit `JAVA_HOME` when multiple JDKs exist.

## Docker on Windows

- Docker Desktop may use **WSL2** backend — containers are Linux unless Windows containers mode is on
- Compose host mounts: `C:\work\app` or `C:/work/app`
- Prefer Linux containers for most open-source stacks

```powershell
docker version
docker compose version
```

## Common failure modes

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `command not found` / `not recognized` | PATH / wrong shell | Refresh PATH; use full path; install toolchain |
| `npm` works, `tsc` doesn't | no global / no npx | `npx tsc` or `npm run` |
| `python` opens Microsoft Store | alias stub | Install Python; disable store alias; use `py` |
| `Activate.ps1` cannot be loaded | ExecutionPolicy | Bypass for that script; or call venv python directly |
| `error MSB8020` / missing MSVC | C++ build tools | Install VS Build Tools (user consent) |
| Scripts with `#!/bin/bash` | Unix scripts | Run under Git Bash/WSL or port to `pwsh` |

## Project bootstrap checklist (Windows)

1. Detect existing tools (`Get-Command`)
2. Prefer lockfiles already in repo (`package-lock.json`, `uv.lock`, etc.)
3. Create venv/node_modules **inside the repo**
4. Use native path activation scripts
5. Document Windows steps in README when you add scripts