asdf Search Ctrl K Guide Reference 0.15.

Guide
What is asdf?
Getting Started
Configuration On this page
.tool-versions
Configuration of asdf encompasses both the sharable .tool-versions files as well as .asdfrc
Usage user specific customisations with .asdfrc and Environment Variables.
Environment Variables
Core Full Configuration Example
Plugins
Versions .tool-versions

Whenever .tool-versions file is present in a directory, the tool versions it declares will
Reference
be used in that directory and any subdirectories.
Configuration
All Commands Note
Plugin Shortname Index Global defaults can be set in the file $HOME/.tool-versions

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

Questions 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

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.

TIP
Multiple versions can be set by separating them with a space. For example, to use Python
3.7.2 , fallback to Python 2.7.15 and finally to the system Python, the following line can be

added to .tool-versions .

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:

txt
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 .

Options Description

no default Use .tool-versions to read versions

yes Use plugin fallback to legacy version files ( .ruby-version ) if available

always_keep_download

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

Options Description

no default Delete source code or binary after successful install

yes Keep source code or binary after install

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.

Options Description

integer in range 1 to
Sync on trigger event if duration (in minutes) since last sync
999999999
has been exceeded
60 is default

0 Sync on each trigger event

never Never sync

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.

Note
Setting the value to never does not stop the plugin repository from being initially synced, for
that behaviour see disable_plugin_short_name_repository .

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.

Options Description

no default Clone or update the asdf plugin repository on sync events

yes Disable the plugin short-name repository

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.

Note
Disabling the plugin short-name repository does not remove the repository if it has already
synced. Remove the plugin repo with rm --recursive --trash $ASDF_DATA_DIR/repository .
Disabling the plugin short-name repository does not remove plugins previously installed from
this source. Plugins can be removed with asdf plugin remove <name> . Removing a plugin will
remove all installed versions of the managed tool.

concurrency

The default number of cores to use during compilation.

Options Description

integer Number of cores to use when compiling the source code

Calculate the number of cores using nproc , then sysctl hw.ncpu , then
auto
/proc/cpuinfo or else 1

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:
text
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:

Configuration Value Calculated by

ASDF_CONFIG_FILE is empty, so use

config file location $HOME/.asdfrc
$HOME/.asdfrc

.tool- ASDF_DEFAULT_TOOL_VERSIONS_FILENAM
default tool versions filename
versions is empty, so use .tool-versions

ASDF_DIR is empty, so use parent d

asdf dir $HOME/.asdf
of bin/asdf

ASDF_DATA_DIR is empty so use

asdf data dir $HOME/.asdf
$HOME/.asdf as $HOME exists.

ASDF_CONCURRENCY is empty, so rely

concurrency auto on concurrency value from the
default configuration

No custom .asdfrc , so use the

legacy_version_file no
default configuration

No custom .asdfrc , so use the

use_release_candidates no
default configuration

No custom .asdfrc , so use the

always_keep_download no
default configuration

No custom .asdfrc , so use the

plugin_repository_last_check_duration 60
default configuration

No custom .asdfrc , so use the

disable_plugin_short_name_repository no
default configuration

Last updated: 24/12/2024, 14 17

Previous page Next page

Versions All Commands