Published on

asdf: A Powerful Version Manager for macOS

Authors
  • Name

Tags:asdfConferenceMacDevOps:YVRTerminalmacOS

Explore asdf, a versatile version manager for macOS that simplifies managing tools and runtimes like Python, Golang, and Terraform in a streamlined workflow. Supplemental notes to my MacDevOps:YVR Conference 2022 session.

asdf is a powerful and flexible version manager for macOS and Linux, designed to streamline the management of multiple programming languages and development tools. With a single CLI interface, you can install, manage, and effortlessly switch between versions of Python, Golang, Terraform, and more. Whether you’re juggling various project requirements or keeping your tools up to date, asdf makes it simple and efficient.

This guide offers a first overview of asdf, focusing on its initial setup and usage on macOS. It also serves as a supplementary resource to my MacDevOps:YVR 2022 conference talk: Runtime and Tools Version Management on macOS. Slides for the talk are available here.

What Makes asdf Stand Out? ​

  • Unified Management: Use one tool to manage versions of diverse runtimes and programming languages.
  • .tool-versions File: Simplify version control across projects using a single configuration file.
  • Plugin-Based Architecture: Add support for a wide range of tools and languages.
  • Local Overrides: Easily define tool versions for specific projects.
  • Less Dependence on Package Managers: Avoid conflicts from package manager installations like Homebrew.

Setting Up asdf on macOS ​

1. Install Prerequisites ​

  1. Install Xcode Command Line Tools:
    bash
    xcode-select --install
  2. Install Core Utilities (choose one method):
  • Homebrew:
    bash
    brew install coreutils
  • GPGTools: Download GPGTools for Mac and custom install MacGPG to /usr/local/MacGPG2.

2. Install asdf ​

Clone the asdf repository to your home directory and set it up:

bash
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.11.3

3. Configure Shell Integration ​

Add the following to your shell configuration file (e.g., ~/.zshrc for zsh):

bash
# Add to your ~/.zshrc
. $HOME/.asdf/asdf.sh
# Append completions to fpath
fpath=(${ASDF_DIR}/completions $fpath)
# Initialize completions with ZSH's compinit
autoload -Uz compinit && compinit

For detailed shell-specific instructions, refer to asdf's documentation.

Getting Started with asdf ​

Key Facts ​

  • Shell Script: asdf is implemented as a shell script.
  • Git-Based Plugins: Plugins fetch available versions and handle installations via Git.
  • Hidden Directory: Everything is stored in ~/.asdf, including installations under ~/.asdf/installs.
  • Configuration File: The .tool-versions file specifies tool versions for directories and projects.

Core Commands ​

  • Set global version:
    bash
    asdf global <name> <version>
  • Set local version for a project:
    bash
    asdf local <name> <version>
  • Install latest version:
    bash
    asdf install <name> latest
  • List installed versions:
    bash
    asdf list <name>
  • List available versions:
    bash
    asdf list all <name>

Python ​

Install the latest Python version:

bash
asdf plugin add python
asdf install python latest
asdf global python latest

Add default Python packages:

bash
# Create $HOME/.default-python-packages
ansible
pipenv

Golang ​

Install Golang with architecture override for Apple Silicon:

bash
asdf plugin add golang
ASDF_GOLANG_OVERWRITE_ARCH=arm64 asdf install golang latest
asdf global golang latest

Node.js ​

Install Node.js:

bash
asdf plugin add nodejs
asdf install nodejs latest
asdf global nodejs latest

Terraform ​

Install Terraform:

bash
asdf plugin add terraform https://github.com/Banno/asdf-hashicorp.git
asdf install terraform latest
asdf global terraform latest

Ruby ​

Install Ruby:

bash
asdf plugin add ruby
asdf install ruby latest
asdf global ruby latest

Updating asdf ​

Update asdf to the latest version:

bash
asdf update

Additional Resources ​

Explore these resources for advanced usage, troubleshooting tips, or to contribute to the asdf community: