Please finish this before the workshop. It takes about 10–15 minutes. Everyone needs the exact same Node version so the packages behave the same for all of us.
npm install, and this has failed on Windows 10 before. On Windows, please use Windows 11 (64-bit). If your laptop runs Windows 10, upgrade to Windows 11, run Ubuntu instead (dual boot or a virtual machine), or contact the organiser before the workshop.
Requirements at a glance
| OS | Minimum | Tool |
|---|---|---|
| Ubuntu (recommended) | Ubuntu 22.04 or 24.04 LTS, 64-bit (other distros with glibc 2.28+ also work) | nvm |
| Windows | Windows 11, 64-bit only (Windows 10 is not supported) | nvm-windows |
| macOS | macOS 11 Big Sur or newer (Intel or Apple Silicon) | nvm |
Install for your operating system
-
Check your Windows version
Press
Win + R, typewinver, press Enter. Or run this in PowerShell:Get-CimInstance Win32_OperatingSystem | Select-Object Caption, BuildNumber, OSArchitecture
You need:
- 64-bit Windows
- Windows 11: the name says "Windows 11" and the build number is
22000or higher
Seeing Windows 10? Stop here. Windows 10 is not supported for this workshop. Upgrade to Windows 11 (Settings → Update & Security → Windows Update, if your PC is eligible), switch to the Ubuntu / Linux tab and run Ubuntu instead, or contact the organiser before the workshop. -
Remove any existing Node.js
nvm-windows will not work properly if Node.js was installed another way.
- Open Settings → Apps, find Node.js, and uninstall it.
- Delete these folders if they still exist:
C:\Program Files\nodejs,%AppData%\npm,%AppData%\npm-cache - Restart your terminal (or the PC).
-
Install build tools for native packages (don't skip this)
This is what most often breaks on Windows: packages that compile C/C++ need Python and the Visual Studio C++ build tools. Open PowerShell as Administrator and run:
winget install --id Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended" winget install --id Python.Python.3.12
No
winget? Install App Installer from the Microsoft Store, or download Build Tools for Visual Studio manually and tick "Desktop development with C++". -
Enable long file paths
node_modulesfolders can exceed Windows' 260-character path limit. In PowerShell as Administrator:New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force git config --global core.longpaths true
(The second line only applies if you have Git installed.)
-
Install nvm-windows
Either use winget:
winget install --id CoreyButler.NVMforWindows
Or download nvm-setup.exe from the nvm-windows releases page and run it with the default options.
Close and reopen your terminal afterwards, then check:
nvm version
-
Install and use Node 22.23.2
Open PowerShell as Administrator (nvm-windows needs admin rights to switch versions):
nvm install 22.23.2 nvm use 22.23.2
-
Allow npm scripts in PowerShell
If you see "running scripts is disabled on this system" when running
npm, run once (normal PowerShell):Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
Optional: Ubuntu on WSL2 (Linux inside Windows 11)
If native packages still fail on Windows 11, WSL2 gives you a real Ubuntu environment where everything installs cleanly. In PowerShell as Administrator:
wsl --install -d Ubuntu
Restart the PC, open Ubuntu from the Start menu, create a user, then follow the Ubuntu / Linux tab instructions inside Ubuntu. Keep your workshop project inside the Linux file system (e.g. ~/workshop), not under /mnt/c.
-
Install Xcode Command Line Tools
Needed for packages that compile native code. Open Terminal and run:
xcode-select --install
If it says they're already installed, you're fine.
-
Remove Homebrew/installer Node (if any)
Check with
which node. If it prints a path like/usr/local/bin/nodeor/opt/homebrew/bin/node, remove it to avoid conflicts:brew uninstall --ignore-dependencies node 2>/dev/null; which node
-
Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
Then reload your shell (or just open a new Terminal window):
source ~/.zshrc
If
nvmis still "command not found", create the profile file and rerun the install:touch ~/.zshrc. -
Install and use Node 22.23.2
nvm install 22.23.2 nvm use 22.23.2 nvm alias default 22.23.2
-
Check your Ubuntu version
lsb_release -ds; uname -m
You want Ubuntu 22.04 or 24.04 LTS on
x86_64oraarch64. Older releases may work but aren't tested for the workshop. -
Remove apt / snap Node (if any)
Node from
aptorsnapwill clash with nvm. Check withwhich -a node, then remove it:sudo apt remove -y nodejs npm 2>/dev/null; sudo snap remove node 2>/dev/null; hash -r
-
Install curl and build tools
Ubuntu / Debian / Ubuntu on WSLFedora / RHELsudo apt update && sudo apt install -y curl build-essential python3
sudo dnf install -y curl gcc-c++ make python3
-
Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
Reload your shell (or open a new terminal):
source ~/.bashrc
-
Install and use Node 22.23.2
nvm install 22.23.2 nvm use 22.23.2 nvm alias default 22.23.2
npm install -g asks for sudo, nvm isn't active — open a new terminal and run nvm use 22.23.2.
Verify your setup
Open a new terminal and run:
node -v npm -v node -p "process.platform + ' ' + process.arch"
Expected output:
v22.23.2 10.x.x win32 x64 (or darwin arm64 / darwin x64 / linux x64)
Native module smoke test
This confirms native packages can be installed on your machine (the issue we hit last time). Run it in an empty folder:
mkdir node-check && cd node-check
npm init -y
npm install bcrypt --build-from-source
node -e "require('bcrypt'); console.log('Native modules OK')"If you see Native modules OK, you're ready. You can delete the node-check folder afterwards.
Pre-workshop checklist
node -vprintsv22.23.2in a fresh terminal- The native module smoke test printed Native modules OK
- Ubuntu users: no apt/snap Node left over (
which -a nodeshows only an.nvmpath) - Windows users: Windows 11 64-bit, build tools installed
- Laptop charger packed and Wi-Fi working
Troubleshooting
nvm is not recognised / command not found
Close all terminal windows and open a new one. On Windows, sign out and back in if it still fails. On macOS/Linux, check that ~/.zshrc or ~/.bashrc contains the NVM_DIR lines added by the installer.
node -v shows a different version
Another Node installation is earlier on your PATH. Run where node (Windows) or which -a node (macOS/Linux) and uninstall anything not managed by nvm. Then run nvm use 22.23.2 again.
Windows: nvm use says "exit status 1" or "Access is denied"
Run the terminal as Administrator. Also make sure your Windows username / nvm install path has no special characters; if it does, reinstall nvm-windows to C:\nvm and set the Node symlink to C:\nodejs during setup.
Windows: gyp ERR!, MSBuild or "Could not find any Visual Studio installation"
The C++ build tools are missing or incomplete. Redo Step 3 in the Windows tab, restart the PC, then retry. If it still fails, switch to the Ubuntu on WSL2 option.
Windows: errors mentioning ENAMETOOLONG or paths that are too long
Enable long paths (Step 4 in the Windows tab), restart, and keep projects in a short path like C:\dev\workshop.
Corporate laptop / proxy blocks downloads
Ask your IT team to allow nodejs.org, registry.npmjs.org and github.com, or use a personal laptop for the workshop.
nvm use <version>.