Skip to content

Troubleshooting Python Global Version Issues with asdf

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:

```sh
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.