Quick Start

Get up and running with vx in 5 minutes.

Prerequisites

• Windows 10+, macOS 10.15+, or Linux (glibc 2.17+)
• Internet connection for first-time tool downloads

Step 1: Install vx

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex

Cargo

cargo install vx

Verify the installation:

vx --version

Step 2: Use Your First Tool

Simply prefix any command with vx. Tools are auto-installed on first use:

# Node.js
vx node --version        # Downloads and installs Node.js, then prints version

# Python
vx python --version      # Downloads and installs Python, then prints version

# Go
vx go version            # Downloads and installs Go, then prints version

Auto-Install

When you run vx <tool> for the first time, vx automatically downloads and installs the latest stable version. No manual setup required!

Step 3: Install Specific Versions

# Install a specific version
vx install node@22
vx install python@3.12
vx install go@1.23

# Install multiple tools at once
vx install node@22 python@3.12 uv@latest

# Use semantic version ranges
vx install "node@^22"    # Latest 22.x.x
vx install "python@~3.12" # Latest 3.12.x

Step 4: Set Up a Project

Create a vx.toml to define your project's toolchain:

cd my-project
vx config init

Edit the generated vx.toml:

[tools]
node = "22"
python = "3.12"
uv = "latest"

[scripts]
dev = "vx node server.js"
test = "vx uv run pytest"
lint = "vx uvx ruff check ."
build = "vx node scripts/build.js"

Install all project tools:

vx setup

Step 5: Run Project Scripts

# Run defined scripts
vx run dev               # Start the dev server
vx run test              # Run tests
vx run lint              # Run linter

# List available scripts
vx run --list

# Pass arguments to scripts
vx run test -- -v --coverage

Step 6: Enter Development Environment

# Enter an interactive shell with all project tools on PATH
vx dev

# Or run a single command in the project environment
vx dev -c "node --version && python --version"

# Export environment for CI/CD
vx dev --export --format github >> $GITHUB_PATH

Step 7: Set Up Shell Integration (Optional)

Enable automatic version switching and tab completions:

Bash

echo 'eval "$(vx shell init bash)"' >> ~/.bashrc

Zsh

echo 'eval "$(vx shell init zsh)"' >> ~/.zshrc

Fish

echo 'vx shell init fish | source' >> ~/.config/fish/config.fish

PowerShell

Add-Content $PROFILE 'Invoke-Expression (vx shell init powershell | Out-String)'

Common Workflows

Node.js Project

vx npx create-react-app my-app
cd my-app
vx npm install
vx npm start

Python Project

vx uv init my-project
cd my-project
vx uv add flask pytest
vx uv run flask run

Go Project

mkdir my-service && cd my-service
vx go mod init github.com/user/my-service
vx go run main.go

Multi-Language Project

# vx.toml
[tools]
node = "22"
python = "3.12"
go = "1.23"
just = "latest"

[scripts]
frontend = "cd frontend && vx npm run dev"
backend = "cd backend && vx go run ."
api = "cd api && vx uv run flask run"
all = "just dev"

Next Steps

• Core Concepts — Understand providers, runtimes, and versions
• Configuration — Deep dive into vx.toml
• CLI Reference — Explore all available commands
• Supported Tools — See the full list of 50+ tools