A blog on software engineering by Trevor Brown

Lua Version Management With Asdf-lua

I’ve written asdf in a past blog post but I haven’t covered asdf-lua in depth yet. In this blog post I’ll talk about the advantages of asdf-lua over existing version managers and show how it’s used.

Lua version management is a pretty small niche. The most popular Lua version manager on GitHub has only 91 stars. asdf-lua isn’t a self-contained Lua version manager but rather a plugin for asdf, and extendable version manager with support for over a dozen languages. Unless you are already using asdf chances are you have several version managers already installed. Rather than installing yet another version manager you can use asdf to manage all the languages you rely on in development. But asdf will work fine with your existing version managers too so you don’t need to worry about uninstalling anything to use asdf-lua. While it might seem like asdf-lua is more complex than other version managers it’s really not. asdf-lua itself is only two short Bash scripts and both asdf and asdf-lua are easy to install and configure as we will see.


If you don’t have asdf installed already you will need to install it. It’s easy:

# Clone the repo, currently the latest release is 0.2.1
git clone ~/.asdf --branch v0.2.1

# Then add two lines to your bashrc or bash_profile if you are on OSX
echo -e '\n. $HOME/.asdf/' >> ~/.bashrc
echo -e '\n. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc

That’s it. After reloading your .bashrc you should be able to run asdf in your shell and see the help printed out. Next install asdf-lua:

asdf plugin-add lua

You will also need a C compiler to compile Lua. Refer to the readme for instructions on getting gcc installed on your OS.

Now that we have asdf-lua and it’s dependencies installed using it to install Lua versions is easy.


To see the Lua versions that are available to install run:

asdf list-all lua

This command will print out a list of all the Lua versions. Find one you want to install and run the installation command. I’ve chosen to install lua 5.3.2:

asdf install lua 5.3.2

After Lua is compiled you can run asdf list lua and you should see the Lua version you just installed. Now that you have a Lua version installed you just need to tell asdf when to use it.

Specifying Lua Versions

asdf looks for a .tool-version file in the current directory and reads it to figure out which version should be used when lua or luac is invoked in that directory. If the file doesn’t exist in the current directory asdf navigates up to the parent directory and checks for it again. This is repeated until a .tool-version file is found on the root directory is reached. Typically you want to set the Lua version on a per-project basis, but you may also want to set a global Lua version so it is available everywhere.

###Setting the Lua version for a project

To set a Lua version for a project cd into the project’s root directory and create the tool version file:

echo "lua 5.3.2" > .tool-version

You should now be able to run lua -v in the directory to see the Lua version being set. You can also use asdf current lua to see the Lua version as well as the path to the .tool-version file that set it. Rather than creating a .tool-version file manually for every project you can the asdf local command to create it for you:

asdf local lua 5.3.2

###Setting a global Lua version

Since asdf is relying on the presence of a .tool-version file in the current directory or one of the parent directories all you need to do to set a global Lua version is to create .tool-version file in your home directory. There is a command that makes this easy:

asdf global lua 5.3.2

This command works just like asdf local only it creates a .tool-version file in your home directory. You can see what it’s written by running less ~/.tool-version. You should now be able to use Lua in any directory under your home directory.


asdf-lua is comparable to other version managers in many ways. The real benefit to asdf-lua is asdf itself. With asdf there is no need to learn the quirks of yet another version manager just to be able to install multiple versions of Lua. The commands I’ve shown here are the exact same for asdf-ruby, asdf-elixir, and all the other asdf plugins.

Feedback is always welcome so if you have any questions about asdf-lua or this blog post feel free to contact me. I’m always looking for ways of improving asdf-lua and asdf so don’t hesitate to contact me if you have any suggestions.


  • asdf:
  • asdf-lua:
  • asdf-ruby:
  • asdf-elixir: