Switch Node.js versions per project
Different repositories need different Node.js versions. Pin the version in each project once, commit it, and every teammate and CI job uses the same one, without remembering to run a switch command.
Pin the version in the project
Run avm node use inside the repository. It writes the version to .avm.json in that directory, so the choice travels with the code.
cd my-app
avm plugin add node
avm node install 22.14.0
avm node use 22.14.0It follows the directory
AVM searches upward from the current directory, nearest file first. Entering another project with a different pin switches Node.js for that project; leaving it falls back to your global default in ~/.avm.json. Plain commands such as node and npm are intercepted through shims, so the right version runs without extra steps.
Use files you already have
If the repository has .nvmrc, .node-version, .tool-versions or an engines.node range in package.json, AVM reads them without any migration. Add .avm.json only when you want to override or add tools such as Java.
Try another version without changing the pin
avm exec runs one command with a temporary version. Project and global pins and lockfiles stay unchanged; a missing runtime is installed automatically unless you pass --no-install.
avm exec node@18 -- npm test
avm x node@22 java@21 -- ./gradlew buildMake it reproducible for the team
Lock fuzzy versions such as 22 to exact releases and commit .avm.lock. New teammates run avm install, and CI runs avm install --frozen, which rejects stale configuration and verifies the locked archive checksums.
avm lock
git add .avm.json .avm.lock
# new machine or CI
avm install --frozen