One Tool to Manage All Your Language Versions

// Before you start

What you need

Mac or Linux computer (Windows users need WSL2)
Terminal app open and ready
curl or git installed (most systems have these by default)
Bash, Zsh, or Fish shell (check by running: echo $SHELL)

Step 1 of 6

Install asdf onto your machine

3 min

This downloads the asdf program itself. The official method uses git to clone the repository into a hidden folder in your home directory. Pick the command that matches your operating system. Most Mac users have Homebrew; most Linux users will use the git method.

Terminal · mac

$ git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.1

What you should see

Cloning into '/home/yourname/.asdf'... done.

This might happen

Command says 'git: command not found'

On Mac run: xcode-select --install On Ubuntu/Debian run: sudo apt install git

Step 2 of 6

Add asdf to your shell so it loads every time

3 min

Right now asdf is downloaded but your terminal does not know about it yet. You need to add two lines to your shell config file so asdf starts automatically. The file you edit depends on your shell. Run 'echo $SHELL' if you are unsure — if it says 'zsh' use the first command; if it says 'bash' use the second. After running the command, close and reopen your terminal completely.

Terminal · mac

$ # If your shell is Zsh (default on modern Macs):

$ echo -e '\n. "$HOME/.asdf/asdf.sh"' >> ~/.zshrc && echo -e '\n. "$HOME/.asdf/completions/asdf.bash"' >> ~/.zshrc

$ # If your shell is Bash (common on Linux):

$ echo -e '\n. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc && echo -e '\n. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc

What you should see

No output is normal. After reopening your terminal, run: asdf --version You should see something like: v0.14.1

This might happen

After reopening the terminal, 'asdf: command not found' still appears

Run: source ~/.zshrc (or source ~/.bashrc for Bash). If that fails, double-check the lines were added by running: cat ~/.zshrc | grep asdf

Step 3 of 6

Install a plugin for the language you want

2 min

asdf uses plugins to support each language. Think of a plugin as a small adapter that teaches asdf how to install a specific language. The example below adds Node.js. Swap 'nodejs' for 'python', 'ruby', 'golang', or any other name from the full plugin list at asdf-vm.com/manage/plugins.html.

Terminal · mac

$ asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

What you should see

initializing plugin repository... done

This might happen

Error about a missing dependency like 'gpg' or 'curl'

On Mac: brew install gpg curl On Ubuntu/Debian: sudo apt install gpg curl dirmngr

Step 4 of 6

Install a specific language version

5 min

Now you can install any version of the language. First list available versions to find the one you want, then install it. The example uses Node.js 20.12.2 — replace the version number with whatever you need. Installation downloads and compiles the version, so it may take a minute or two.

Terminal · mac

$ # See all available Node.js versions:

$ asdf list all nodejs

$ # Install a specific version (replace 20.12.2 with your chosen version):

$ asdf install nodejs 20.12.2

What you should see

Downloading node-v20.12.2... Installing node-v20.12.2... node-v20.12.2 installed

This might happen

Installation fails with a build error or missing package

On Ubuntu/Debian run: sudo apt install build-essential libssl-dev On Mac run: xcode-select --install Then retry the install command.

Step 5 of 6

Set the version to use globally or per project

2 min

You have the version installed, but asdf still needs to know when to use it. 'global' sets a default for your whole computer. 'local' creates a tiny file called .tool-versions inside your current folder, so that project always uses that version automatically. Use global first to get started, then use local inside specific project folders later.

Terminal · mac

$ # Set as the default version for your whole computer:

$ asdf global nodejs 20.12.2

$ # OR set only for the current project folder:

$ asdf local nodejs 20.12.2

$ # Confirm it works:

$ node --version

What you should see

v20.12.2

This might happen

node --version still shows the old system version or 'command not found'

Run: asdf reshim nodejs This rebuilds the internal shortcuts asdf uses. Then try node --version again.

Step 6 of 6

Check what is installed and switch versions anytime

1 min

These are the everyday commands you will use going forward. List installed versions, see which is active, and switch between them whenever a project needs a different version. asdf automatically reads the .tool-versions file in any folder, so switching projects means the right version loads without you doing anything.

Terminal · mac

$ # See all installed versions of a language:

$ asdf list nodejs

$ # See all currently active versions across all languages:

$ asdf current

$ # Install another version and switch to it:

$ asdf install nodejs 18.20.2

$ asdf global nodejs 18.20.2

What you should see

asdf current shows a table like: nodejs 18.20.2 /home/yourname/.tool-versions

// Status

cooked. baked. worked.

A working asdf installation that can install and switch between versions of Node.js (or any other supported language) with a single command. Project folders with a .tool-versions file will automatically use the correct version.

// the honest bit

The honest part

asdf is a developer tool at heart — it solves a real problem but assumes you are comfortable in a terminal. The setup is straightforward copy-paste, but if something breaks it usually means a missing system dependency, and fixing that may require reading an error message carefully. Windows is not natively supported; you must use WSL2. Some plugins (especially older ones) have their own extra dependencies not covered here — always check the plugin's own README on GitHub if an install fails.