Getting Started with asdf for Tool and Runtime Management

Managing multiple versions of tools and runtimes can get complex fast. For example, depending on the version of macOS you’re running, you will likely have at least two versions of Python installed, if not more. And for iOS developers, it is very common to run into a similar situation with Ruby and others as well. The same is true for managing multiple versions of tools, such as CLIs, which each have their own configurations and API version targets.

When running things manually in a development environment, managing multiple versions of a given runtime or tool is relatively simple, but can be tedious and time consuming, and when it comes to automating processes for continuous integration and deployment (CI/CD) pipelines, it can get downright unruly.

Today, we’ll take a look at asdf, a tool designed to simplify managing multiple versions of a given tool or runtime that is well suited to macOS. Additionally, it has the added benefit of helping distributed teams ensure that they are each using the exact same version of a given tool.

As an example, we’ll tackle the problem of managing multiple versions of Python with asdf and pipenv on macOS, in order to facilitate the isolation of specific dependencies required by one version or the other.

However, it is certainly worth noting that asdf is in no way specific to managing Python. In fact, there are a very large number of similar plugins available in order to manage all manner of tool and runtime versions. And if there isn’t a plugin for the tool you need to manage, there are guidelines for developing a custom plugin as well.

Install asdf on macOS

We can install asdf on macOS with Homebrew, like so:

brew install asdf

Install the asdf Python Plugin

In order to use the plugin, we’ll first have to install its dependencies:

brew install openssl readline sqlite3 xz zlib tcl-tk

And then we can install the plugin itself:

asdf plugin-add python

Adding Default Packages

We’ll need to ensure that pipenv is available for each of our Python versions, and we can accomplish that by creating a hidden file in our HOME directory called .default-python-packages, like so:

touch $HOME/.default-python-packages && vim $HOME/.default-python-packages

We’ll then need to add pipenv to the file, and then exit vim by typing: esc then : and finally: wq followed by enter. (Of course, you can use any text editor you like here. We’re just using vim for convenience).

pipenv
~                                                                               
~                                                                               
~

Installing Specific Python Versions with asdf

With the above in place, we can now get on to the task of installing the specific versions of Python that we need. To see all available Python versions for installation via asdf, you can run:

 asdf list-all python

It just so happens that our imaginary project requires the latest stable version of Python along with Python3.9. In order to add those to our machine, we can run the following:

asdf install python latest

asdf install python pypy3.9-7.3.8

Once they are each installed, we can use pipenv, which is now available because we added it to our list of required default packages above, to create a Python virtual environment for each of our new Python versions. This will serve to isolate version-specific packages, so we can work in both of our required versions.

To test this, we can create a directory called python3.9, enter it, and create a virtual environment that uses Python3.9 by default (and confirm success by opening a Python shell) like so:

mkdir python3.9 && cd python3.9

pipenv --python pypy3.9-7.3.8

jeff@Jeffs-Air python3.9 % pipenv shell
Launching subshell in virtual environment...
 . /Users/jeff/.local/share/virtualenvs/python3.9-LMOMqMzM/bin/activate
jeff@Jeffs-Air python3.9 %  . /Users/jeff/.local/share/virtualenvs/python3.9-LMOMqMzM/bin/activate
(python3.9) jeff@Jeffs-Air python3.9 %

(python3.9) jeff@Jeffs-Air python3.9 %python
Python 3.9.10 (8276b505180f70c5784a698a510f0a17317a85c3, Feb 19 2022, 16:51:03)
[PyPy 7.3.8 with GCC Apple LLVM 13.0.0 (clang-1300.0.29.30)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>> 

We can then go through the same process in a new directory for python3.10, like so:

mkdir python3.10 && cd python3.10

pipenv --python 3.10.5

pipenv shell
Launching subshell in virtual environment...
Restored session: Tue Jun 28 15:57:39 PDT 2022
 . /Users/jeff/.local/share/virtualenvs/python3.10-QhE7TF4C/bin/activate        
jeff@Jeffs-Air python3.10 %  . /Users/jeff/.local/share/virtualenvs/python3.10-QhE7TF4C/bin/activate

(python3.10) jeff@Jeffs-Air python3.10 % python
Python 3.10.5 (main, Jun 28 2022, 14:50:38) [Clang 13.1.6 (clang-1316.0.21.2.3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>

TL;DR

asdf is a powerful, light-weight tool for managing multiple versions of a given tool or runtime. Above, we demonstrated this by using asdf and pipenv to install and isolate multiple versions of Python on the same macOS machine, which is just one of a great many tools and runtimes that can easily be managed with asdf.