Installation Guide

Learn how to install and configure asdf

guide

Getting started with asdf is a straightforward process once you understand the prerequisites, installation steps, and common pitfalls. This guide walks you through each stage in a clear, technical yet accessible manner.

Prerequisites

Git – required to clone the asdf repository.
Shell – a modern shell (bash, zsh, fish, etc.) is needed for initialization.
Network – a working internet connection is essential for downloading plugins and language binaries.
Build tools – on Linux/macOS you must have gcc, make, autoconf, automake, libtool, and pkg-config to compile language binaries.
Windows – use the Windows Subsystem for Linux (WSL) or the asdf‑windows fork.

Installation

Clone the asdf repository into the directory that will become ASDF_HOME (default ~/.asdf):
```
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.12.0
```
Add the asdf initialization script to your shell’s startup file:
- bash:
```
echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.bashrc
echo -e '\n. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc
```
- zsh – add the same lines to ~/.zshrc.
- fish – source ~/.asdf/asdf.fish in config.fish.
Reload the shell or run source ~/.bashrc (or the appropriate file) to activate asdf.

Configuration

~/.asdf stores asdf’s core files.
Set ASDF_DIR to change the root directory.
The data directory (where plugin data and installed versions live) defaults to ~/.asdf/installs and can be overridden with ASDF_DATA_DIR.

Plugin Management

Add a plugin:

asdf plugin-add <name>          # uses the official plugin list
asdf plugin-add <name> <repo>   # specify a custom repo

List available versions:
```
asdf list-all <name>
```

Update a plugin or all plugins:

asdf plugin-update <name>
asdf plugin-update all

Remove a plugin:
```
asdf plugin-remove <name>
```

Installing Language Versions

Install a specific version:
```
asdf install <name> <version>
```
Set a global default:
```
asdf global <name> <version>
```
Set a local project‑specific version (creates .tool-versions):
```
asdf local <name> <version>
```
After installing or changing versions, regenerate shims:
```
asdf reshim
```

Shell Integration
asdf automatically prepends the selected version’s binary directory to your PATH. Verify with:

asdf which <executable>

(e.g., asdf which node).

Updating asdf
Pull the latest changes from the repo and switch to the desired tag:

cd ~/.asdf && git pull && git checkout v0.12.0

Then reload the shell.

Common Commands

asdf current <name> – show the currently active version.
asdf list <name> – list installed versions.
asdf uninstall <name> <version> – remove an installed version.

Troubleshooting

Permission errors – ensure ~/.asdf is owned by your user.

Missing build tools – on Ubuntu, install:

sudo apt-get install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl git

Plugin failures – some plugins require additional dependencies (e.g., nodejs needs openssl). Check the plugin’s README.
PATH issues – verify that the asdf init script is sourced before other PATH modifications.

Windows (WSL or asdf‑windows)

WSL – install WSL, then follow the Linux instructions above.
Native Windows – clone the asdf‑windows fork:
```
git clone https://github.com/asdf-community/asdf-windows.git C:\asdf
```
Add C:\asdf\bin to the system PATH. Then run asdf init in a PowerShell session to set up the environment.