Getting Started
1. Install asdf
asdf can be installed in several different ways:
With Package Manager -Recommended
Package Manager | Command |
---|---|
Homebrew | brew install asdf |
Zypper | zypper install asdf |
Pacman | git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si or use your preferredAUR helper |
Download Pre-Compiled Binary -Easy
Install Dependencies
asdf primarily requiresgit
. Here is anon-exhaustive list of commands to run foryour package manager (some might automatically install these tools in later steps).
OS | Package Manager | Command |
---|---|---|
linux | Aptitude | apt install git bash |
linux | DNF | dnf install git bash |
linux | Pacman | pacman -S git bash |
linux | Zypper | zypper install git bash |
macOS | Homebrew | brew install coreutils git bash |
macOS | Spack | spack install coreutils git bash |
Note
sudo
may be required depending on your system configuration.
Please see theDependencies page for more information.
Install asdf
- Visithttps://github.com/asdf-vm/asdf/releases and download the appropriate archive for your operating system/architecture combination.
- Extract the
asdf
binary in the archive into a directory on your$PATH
. - Verify
asdf
is on your shell's$PATH
by runningtype -a asdf
. The directory you placed theasdf
binary in should be listed on the first line of the output fromtype
. If it is not that means step #2 was not completed correctly.
Withgo install
Install Dependencies
asdf primarily requiresgit
. Here is anon-exhaustive list of commands to run foryour package manager (some might automatically install these tools in later steps).
OS | Package Manager | Command |
---|---|---|
linux | Aptitude | apt install git bash |
linux | DNF | dnf install git bash |
linux | Pacman | pacman -S git bash |
linux | Zypper | zypper install git bash |
macOS | Homebrew | brew install coreutils git bash |
macOS | Spack | spack install coreutils git bash |
Note
sudo
may be required depending on your system configuration.
Please see theDependencies page for more information.
Install asdf
- Install Go
- Run
go install github.com/asdf-vm/asdf/cmd/asdf@v0.18.0
Build from Source
Install Dependencies
asdf primarily requiresgit
. Here is anon-exhaustive list of commands to run foryour package manager (some might automatically install these tools in later steps).
OS | Package Manager | Command |
---|---|---|
linux | Aptitude | apt install git bash |
linux | DNF | dnf install git bash |
linux | Pacman | pacman -S git bash |
linux | Zypper | zypper install git bash |
macOS | Homebrew | brew install coreutils git bash |
macOS | Spack | spack install coreutils git bash |
Note
sudo
may be required depending on your system configuration.
Please see theDependencies page for more information.
Install asdf
- Clone the asdf repository:
git clone https://github.com/asdf-vm/asdf.git --branch v0.18.0
- Run
make
- Copy the
asdf
binary into a directory on your$PATH
. - Verify
asdf
is on your shell's$PATH
by runningtype -a asdf
. The directory you placed theasdf
binary in should be listed on the first line of the output fromtype
. If it is not that means step #3 was not completed correctly.
2. Configure asdf
Note
Most usersDO NOT need to customize the location that asdf writes plugin, install, and shim data to. However, if$HOME/.asdf
isn't the directory you want asdf writing to, you can change it. Specify the directory by exporting a variable namedASDF_DATA_DIR
in your shell's RC file.
There are many different combinations of Shells, OSs & Installation methods all of which affect the configuration here. Expand the selection below that best matches your system.
macOS users, be sure to read the warning aboutpath_helper
at the end of this section.
Bash
macOS Catalina or newer: The default shell has changed toZSH. Unless changing back to Bash, follow the ZSH instructions.
Pacman:bash-completion
needs to be installed for the completions to work.
Add shims directory to path (required)
Add the following to~/.bash_profile
:
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"
Custom data directory (optional)
Add the following to~/.bash_profile
above the line you added above:
export ASDF_DATA_DIR="/your/custom/data/dir"
Set up shell completions (optional)
Completions must be configured by adding the following to your.bashrc
:
. <(asdf completion bash)
Fish
Add shims directory to path (required)
Add the following to~/.config/fish/config.fish
:
# ASDF configuration codeif test -z $ASDF_DATA_DIR set _asdf_shims "$HOME/.asdf/shims"else set _asdf_shims "$ASDF_DATA_DIR/shims"end# Do not use fish_add_path (added in Fish 3.2) because it# potentially changes the order of items in PATHif not contains $_asdf_shims $PATH set -gx --prepend PATH $_asdf_shimsendset --erase _asdf_shims
Custom data directory (optional)
Pacman: Completions are automatically configured on installation by the AUR package.
Add the following to~/.config/fish/config.fish
above the lines you added above:
set -gx --prepend ASDF_DATA_DIR "/your/custom/data/dir"
Set up shell completions (optional)
Completions must be configured manually with the following command:
$ asdf completion fish > ~/.config/fish/completions/asdf.fish
Elvish
Add shims directory to path (required)
Add the following to~/.config/elvish/rc.elv
:
var asdf_data_dir = ~'/.asdf'if (and (has-envASDF_DATA_DIR) (!=s $E:ASDF_DATA_DIR '')) { set asdf_data_dir = $E:ASDF_DATA_DIR}if (not (has-value $paths $asdf_data_dir'/shims')) { set paths = [$path $@paths]}
Custom data directory (optional)
Change the following line in the above snippet to set a custom data directory:
-var asdf_data_dir = ~'/.asdf'+var asdf_data_dir = '/your/custom/data/dir'
Set up shell completions (optional)
$ asdf completion elvish >> ~/.config/elvish/rc.elv$ echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv
ZSH
Pacman: Completions are placed in a ZSH friendly location, butZSH must be configured to use the autocompletions.
Add shims directory to path (required)
Add the following to~/.zshrc
:
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"
Custom data directory (optional)
Add the following to~/.zshrc
above the line you added above:
export ASDF_DATA_DIR="/your/custom/data/dir"
Set up shell completions (optional)
Completions are configured by either a ZSH Frameworkasdf
plugin (likeasdf for oh-my-zsh) or by doing the following:
$ mkdir -p "${ASDF_DATA_DIR:-$HOME/.asdf}/completions"$ asdf completion zsh > "${ASDF_DATA_DIR:-$HOME/.asdf}/completions/_asdf"
Then add the following to your.zshrc
:
# append completions to fpathfpath=(${ASDF_DATA_DIR:-$HOME/.asdf}/completions $fpath)# initialise completions with ZSH's compinitautoload -Uz compinit &&compinit
Note
If you are using a customcompinit
setup with a ZSH Framework, ensurecompinit
is below your sourcing of the framework
Completions are configured by either a ZSH Frameworkasdf
or will need to beconfigured as per Homebrew's instructions. If you are using a ZSH Framework the associated plugin for asdf may need to be updated to use the new ZSH completions properly viafpath
. The Oh-My-ZSH asdf plugin is yet to be updated, seeohmyzsh/ohmyzsh#8837.
PowerShell Core
Add shims directory to path (required)
Add the following to~/.config/powershell/profile.ps1
:
# Determine the location of the shims directoryif ($null -eq $ASDF_DATA_DIR -or $ASDF_DATA_DIR -eq'') { $_asdf_shims= "${env:HOME}/.asdf/shims"}else { $_asdf_shims= "$ASDF_DATA_DIR/shims"}# Then add it to path$env:PATH ="${_asdf_shims}:${env:PATH}"
Custom data directory (optional)
Add the following to~/.config/powershell/profile.ps1
above the snippet you added above:
$env:ASDF_DATA_DIR ="/your/custom/data/dir"
Shell completions not available for PowerShell
Nushell
Add shims directory to path (required)
Add the following to~/.config/nushell/config.nu
:
let shims_dir = ( if ( $env| get --ignore-errors ASDF_DATA_DIR | is-empty ) { $env.HOME | path join '.asdf' }else { $env.ASDF_DATA_DIR }| path join 'shims')$env.PATH = ( $env.PATH | split row (charesep)| where { |p| $p!= $shims_dir} | prepend $shims_dir )
Custom data directory (optional)
Add the following to~/.config/nushell/config.nu
above the line you added above:
$env.ASDF_DATA_DIR ="/your/custom/data/dir"
Set up shell completions (optional)
# If you've not customized the asdf data directory:$ mkdir $"($env.HOME)/.asdf/completions"$ asdf completion nushell | save $"($env.HOME)/.asdf/completions/nushell.nu"# If you have customized the data directory by setting ASDF_DATA_DIR:$ mkdir $"($env.ASDF_DATA_DIR)/completions"$ asdf completion nushell | save $"($env.ASDF_DATA_DIR)/completions/nushell.nu"
Then add the following to~/.config/nushell/config.nu
:
let asdf_data_dir = ( if ( $env| get --ignore-errors ASDF_DATA_DIR | is-empty ) { $env.HOME | path join '.asdf' }else { $env.ASDF_DATA_DIR }). "$asdf_data_dir/completions/nushell.nu"
POSIX Shell
Add shims directory to path (required)
Add the following to~/.profile
:
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"
Custom data directory (optional)
Add the following to~/.profile
above the line you added above:
export ASDF_DATA_DIR="/your/custom/data/dir"
asdf
scripts need to be sourcedafter you have set your$PATH
andafter you have sourced your framework (oh-my-zsh etc).
Restart your shell so thatPATH
changes take effect. Opening a new terminal tab will usually do it.
Core Installation Complete!
This completes the installation of theasdf
core 🎉
asdf
is only useful once you install aplugin, install atool and manage itsversions. Continue the guide below to learn how to do this.
4. Install a Plugin
For demonstration purposes we will install & setNode.js via theasdf-nodejs
plugin.
Plugin Dependencies
Each plugin has dependencies so we need to check the plugin repo where they should be listed. Forasdf-nodejs
they are:
OS | Dependency Installation |
---|---|
Debian | apt-get install dirmngr gpg curl gawk |
CentOS/ Rocky Linux/ AlmaLinux | yum install gnupg2 curl gawk |
macOS | brew install gpg gawk |
We should install dependencies first as some Plugins have post-install hooks.
Install the Plugin
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
5. Install a Version
Now we have a plugin for Node.js we can install a version of the tool.
We can see which versions are available withasdf list all nodejs
or a subset of versions withasdf list all nodejs 14
.
We will just install thelatest
available version:
asdf install nodejs latest
Note
asdf
enforces exact versions.latest
is a helper throughoutasdf
that will resolve to the actual version number at the time of execution.
6. Set a Version
asdf
performs a version lookup of a tool in all.tool-versions
files from the current working directory up to the$HOME
directory. The lookup occurs just-in-time when you execute a tool thatasdf
manages.
WARNING
Without a version listed for a tool execution of the tool willerror.asdf current
will show you the tool & version resolution, or absence of, from your current directory so you can observe which tools will fail to execute.
Because asdf looks for a.tool-versions
file in the current directory first, and if the file is not found it then climbs up the file tree looking for a.tool-versions
in a parent directory until it finds one. If no.tool-versions
file is found the version resolution process will fail and an error will be printed.
If you want to set a default version that will apply to all directories you work in you can set a version in$HOME/.tool-versions
. Any directory under your home directory will have that same version set, unless a particular directory sets another version.
asdf set -u nodejs 16.5.0
$HOME/.tool-versions
will then look like:
nodejs 16.5.0
Some OSs already have tools installed that are managed by the system and notasdf
,python
is a common example. You need to tellasdf
to pass the management back to the system. TheVersions reference section will guide you.
The first place asdf looks for a version is your current working directory ($PWD/.tool-versions
). This may be a directory containing a source code or Git repository for a project. When in your desired directory execute you can useasdf set
to set the version:
asdf set nodejs 16.5.0
$PWD/.tool-versions
will then look like:
nodejs 16.5.0
Using Existing Tool Version Files
asdf
supports the migration from existing version files from other version managers. Eg:.ruby-version
for the case ofrbenv
. This is supported on a per-plugin basis.
asdf-nodejs
supports this via both.nvmrc
and.node-version
files. To enable this, add the following to yourasdf
configuration file$HOME/.asdfrc
:
legacy_version_file = yes
See theconfiguration reference page for more config options.
Guide Complete!
That completes the Getting Started guide forasdf
🎉 You can now managenodejs
versions for your project. Follow similar steps for each type of tool in your project!
asdf
has many more commands to become familiar with, you can see them all by runningasdf --help
orasdf
. The core of the commands are broken into three categories: