Configuration ​

Configuration of asdf encompasses both the sharable .tool-versions files as well as user specific customisations with .asdfrc and Environment Variables.

.tool-versions ​

Whenever .tool-versions file is present in a directory, the tool versions it declares will be used in that directory and any subdirectories.

This is what a .tool-versions file looks like:

ruby 2.5.3
nodejs 10.15.0

ruby 2.5.3
nodejs 10.15.0

You can also include comments:

ruby 2.5.3 # This is a comment
# This is another comment
nodejs 10.15.0

ruby 2.5.3 # This is a comment
# This is another comment
nodejs 10.15.0

The versions can be in the following format:

• 10.15.0 - an actual version. Plugins that support downloading binaries, will download binaries.
• ref:v1.0.2-a or ref:39cb398vb39 - tag/commit/branch to download from github and compile
• path:~/src/elixir - a path to custom compiled version of a tool to use. For use by language developers and such.
• system - this keyword causes asdf to passthrough to the version of the tool on the system that is not managed by asdf.

python 3.7.2 2.7.15 system

python 3.7.2 2.7.15 system

To install all the tools defined in a .tool-versions file run asdf install with no other arguments in the directory containing the .tool-versions file.

To install a single tool defined in a .tool-versions file run asdf install <name> in the directory containing the .tool-versions file. The tool will be installed at the version specified in the .tool-versions file.

Edit the file directly or use asdf local (or asdf global) which updates it.

.asdfrc ​

The .asdfrc file defines the user's machine specific configuration.

${HOME}/.asdfrc is the default location used by asdf. This can be set with the Environment Variable ASDF_CONFIG_FILE.

The below file shows the required format with the default values:

legacy_version_file = no
use_release_candidates = no
always_keep_download = no
plugin_repository_last_check_duration = 60
disable_plugin_short_name_repository = no
concurrency = auto

legacy_version_file = no
use_release_candidates = no
always_keep_download = no
plugin_repository_last_check_duration = 60
disable_plugin_short_name_repository = no
concurrency = auto

legacy_version_file ​

Plugins with support can read the versions files used by other version managers, for example, .ruby-version in the case of Ruby's rbenv.

use_release_candidates ​

Configure the asdf update command to upgrade to the latest Release Candidate instead of the latest Semantic Version.

always_keep_download ​

Configure the asdf install command to keep or delete the source code or binary it downloads.

plugin_repository_last_check_duration ​

Configure the duration (in minutes) between asdf plugin repository syncs. Trigger events result in a check of the duration. If more time has elapsed since the last sync than specified in the duration, a new sync occurs.

Sync events occur when the following commands are executed:

• asdf plugin add <name>
• asdf plugin list all

asdf plugin add <name> <git-url> does NOT trigger a plugin sync.

disable_plugin_short_name_repository ​

Disable synchronization of the asdf plugin short-name repository. Sync events will exit early if the short-name repository is disabled.

Sync events occur when the following commands are executed:

• asdf plugin add <name>
• asdf plugin list all

asdf plugin add <name> <git-url> does NOT trigger a plugin sync.

concurrency ​

The default number of cores to use during compilation.

Note: the environment variable ASDF_CONCURRENCY take precedence if set.

Plugin Hooks ​

It is possible to execute custom code:

• Before or after a plugin is installed, reshimed, updated, or uninstalled
• Before or after a plugin command is executed

For example, if a plugin called foo is installed and provides a bar executable, then the following hooks can be used to execute custom code first:

pre_foo_bar = echo Executing with args: $@

pre_foo_bar = echo Executing with args: $@

The following patterns are supported:

• pre_<plugin_name>_<command>
• pre_asdf_download_<plugin_name>
• {pre,post}_asdf_{install,reshim,uninstall}_<plugin_name>
  • $1: full version
• {pre,post}_asdf_plugin_{add,update,remove,reshim}
  • $1: plugin name
• {pre,post}_asdf_plugin_{add,update,remove}_<plugin_name>

See Create a Plugin for specifics on what command hooks are ran before or after what commands.

Environment Variables ​

Setting environment variables varies depending on your system and Shell. Default locations depend upon your installation location and method (Git clone, Homebrew, AUR).

Environment variables should generally be set before sourcing asdf.sh/asdf.fish etc. For Elvish set above use asdf.

The following describe usage with a Bash Shell.

ASDF_CONFIG_FILE ​

Path to the .asdfrc configuration file. Can be set to any location. Must be an absolute path.

• If Unset: $HOME/.asdfrc will be used.
• Usage: export ASDF_CONFIG_FILE=/home/john_doe/.config/asdf/.asdfrc

ASDF_DEFAULT_TOOL_VERSIONS_FILENAME ​

The filename of the file storing the tool names and versions. Can be any valid filename. Typically, you should not set this value unless you want to ignore .tool-versions files.

• If Unset: .tool-versions will be used.
• Usage: export ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=tool_versions

ASDF_DIR ​

The location of asdf core scripts. Can be set to any location. Must be an absolute path.

• If Unset: the parent directory of the bin/asdf executable is used.
• Usage: export ASDF_DIR=/home/john_doe/.config/asdf

ASDF_DATA_DIR ​

The location where asdf will install plugins, shims and tool versions. Can be set to any location. Must be an absolute path.

• If Unset: $HOME/.asdf if it exists, or else the value of ASDF_DIR
• Usage: export ASDF_DATA_DIR=/home/john_doe/.asdf

ASDF_CONCURRENCY ​

Number of cores to use when compiling the source code. If set, this value takes precedence over the asdf config concurrency value.

• If Unset: the asdf config concurrency value is used.
• Usage: export ASDF_CONCURRENCY=32

ASDF_FORCE_PREPEND ​

Whether or not to prepend the asdf shims and path directories to the front-most (highest-priority) part of the PATH.

• If Unset: On macOS, defaults to yes; but on other systems, defaults to no
• If yes: Force asdf directories to the front of the PATH
• If set to any string other than yes: Do not force asdf directories to the front of the PATH
• Usage: ASDF_FORCE_PREPEND=no . "<path-to-asdf-directory>/asdf.sh"

Full Configuration Example ​

Following a simple asdf setup with:

• a Bash Shell
• an installation location of $HOME/.asdf
• installed via Git
• NO environment variables set
• NO custom .asdfrc file

would result in the following outcomes:

Internal Configuration ​

Users should not worry about this section as it describes configuration internal to asdf useful for Package Managers and integrators.

• $ASDF_DIR/asdf_updates_disabled: Updates via the asdf update command are disabled when this file is present (content irrelevant). This is used by package managers like Pacman or Homebrew to ensure the correct update method is used for the particular installation.