CRUD.cloud

Troubleshooting Python Global Version Issues with asdf

Update, October 2026: I'm keeping this article as I wrote it in 2024. Some things have changed since then, so read Before You Try This Today before you copy the commands.

asdf is a versatile version manager that simplifies handling multiple language runtimes on your system. If you're encountering discrepancies between your expected Python version and what your system reports, this guide can help.

The Problem: asdf Global Version Not Taking Effect

Initially, I had Python 3.12.2 installed and wanted to upgrade to 3.13.0. I used asdf to install the new version:

asdf install python 3.13.0

Then, I set the global Python version using asdf:

asdf global python 3.13.0

However, checking the Python version still showed 3.12.2:

python --version
Python 3.12.2

This indicates that while asdf recognised the new version, it wasn't being used by the system.

Debugging and Resolution

The key to understanding this issue lies in how asdf manages versions. asdf often stores version configurations in a .tool-versions file.

To investigate, I used asdf current to see the currently active versions:

asdf current
Name      Version    Source
golang    ______     ______
nodejs    20.11.0    /Users/cruder/.tool-versions
python    3.12.2     /Users/cruder/.tool-versions
ruby      3.4.2      /Users/cruder/.tool-versions

This confirmed that asdf was reading the Python version from ~/.tool-versions.

Next, I examined the contents of ~/.tool-versions:

cat ~/.tool-versions
nodejs 20.11.0
python 3.12.2
ruby 3.4.2

As expected, the Python version was still set to 3.12.2.

The Fix: Manually Updating .tool-versions

The asdf global command should update this file, but in some cases, a manual edit is necessary. I updated the Python line to reflect the desired version:

echo "python 3.13.0" | sed -i '' '/^python/d' ~/.tool-versions
echo "python 3.13.0" >> ~/.tool-versions

(Or you can use a text editor to directly edit the file^^)

Now, ~/.tool-versions looks like this:

cat ~/.tool-versions
nodejs 20.11.0
python 3.13.0
ruby 3.4.2

Finally, checking the Python version confirmed the change:

python --version
Python 3.13.0

Key Takeaways

  • .tool-versions Importance: asdf relies heavily on the .tool-versions file for managing global and local versions.
  • Troubleshooting asdf global: If asdf global doesn't seem to have an effect, directly inspecting and editing .tool-versions can be a quick solution.
  • Verify with asdf current: Always use asdf current to verify the active versions managed by asdf.
  • Shell Restart: In some cases, you may need to restart your shell (e.g., exec $SHELL) or open a new terminal for the changes to take effect.

By understanding how asdf manages versions and where it stores configuration, you can effectively troubleshoot and resolve version-related issues.

Before You Try This Today

Added on 2026-10-20. The article above is unchanged since 2024-11-02; these are the gotchas you may hit if you follow it today.

  • asdf global doesn't exist any more. asdf 0.16.0 was a full rewrite in Go and removed global and local. Today the fix is one command: asdf set -u python 3.13.0 (or --home) writes the version to ~/.tool-versions. asdf set without a flag writes to the current directory, like the old local.
  • After upgrading to 0.16+, check your shell setup. The rewrite changed how asdf is loaded: the shims directory must be on your PATH. A leftover setup from the old version is a common reason python --version keeps showing the old version. Follow the upgrade guide below.
  • A .tool-versions closer to where you are wins. A file in the current directory, or a parent, overrides the one in your home directory. The Source column of asdf current tells you which file is used, as shown above.
  • The sed line is macOS-only, and the echo | in front of it does nothing. On Linux, use sed -i '/^python/d' ~/.tool-versions. Or simply run asdf set -u and let asdf edit the file.
  • Run asdf reshim python if a newly installed version's commands aren't found.

References

Links checked on 2026-10-20.