asdf-vm / asdf-vm/asdf

bug: multiple version selection does not work as documented

Open
#2,188 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
Go
Stars
25.6k
Forks
941
Avg merge
9h 24m
Merged PRs (30d)
3

Description

### Describe the Bug

In https://asdf-vm.com/manage/configuration.html#tool-versions we are told:

> [!TIP]
>
> Multiple versions can be set by separating them with a space. For example, to use Python 3.7.2, fallback to Python 2.7.15 and finally to the system Python, the following line can be added to .tool-versions.
>
> ```
> python 3.7.2 2.7.15 system
> ```

The observed behaviour is that the latest version in the list is used; there is no fallback from first to last.

Either the documentation is wrong, or `asdf` is selecting the wrong version.

### Steps to Reproduce

```shell
$ # Validate asdf is in play ------------------------------------------------------------

$ which python
python: aliased to python3
$ which python3
/Users/nunya/.asdf/shims/python3

$ # Expect 3.10.7 to be used ------------------------------------------------------------

$ cat .tool-versions
python 3.10.17 3.11.8 3.12.11 3.13.3 system

$ asdf current python
Name Version Source Installed
python 3.10.17 3.11.8 3.12.11 3.13.3 /Users/dbingham/repos/mntv-python-guild/smlib.cache/.tool-versions true

$ asdf list python
3.10.14
*3.10.17
3.11.6
*3.11.8
*3.12.11
3.13.0
3.13.1
3.13.2
*3.13.3
3.9.11
3.9.21

$ python --version
Python 3.13.3

$ # Edit/save .tool-versions with various ordering --------------------------------------

$ cat .tool-versions
python 3.11.8 3.13.3 3.12.11 system 3.10.17

$ python --version
Python 3.13.3

$ cat .tool-versions
python 3.12.11 system 3.11.8 3.13.3 3.10.17

$ python --version
Python 3.13.3

$ # Clip the most recent version out ---------------------------------------------------

$ cat .tool-versions
python 3.12.11 system 3.11.8 3.10.17

$ python --version
Python 3.12.11
```

### Expected Behaviour

According to the documentation, the list of versions to select should be considered from first to last. In that order, the first version that is installed should be used, and therefore should be the version presented by `python --version`.

### Actual Behaviour

The most-recently-released version of all those in the list is used, regardless of the order of the versions in the list.

### Environment

```shell
asdf info
OS:
Darwin G77VW6GPCV 24.6.0 Darwin Kernel Version 24.6.0: Mon Jul 14 11:28:30 PDT 2025; root:xnu-11417.140.69~1/RELEASE_ARM64_T6030 arm64

SHELL:
zsh 5.9 (arm64-apple-darwin24.0)

BASH VERSION:
3.2.57(1)-release

ASDF VERSION:
0.16.7

ASDF INTERNAL VARIABLES:
ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=.tool-versions
ASDF_DATA_DIR=/Users/nunya/.asdf
ASDF_CONFIG_FILE=/Users/nunya/.asdfrc

ASDF INSTALLED PLUGINS:
nodejs https://github.com/asdf-vm/asdf-nodejs.git 90b8ecaa556916daba983a7b01869a9ea682f285
python https://github.com/danhper/asdf-python.git d4caa7d4832313b4c141ee0ceca4118747147e89
ruby https://github.com/asdf-vm/asdf-ruby.git 26be0ebf43b47dba9bf244995700deeaa572b281
yarn https://github.com/twuni/asdf-yarn.git 376c5407ef22c82fa56e4bd9f6a9108354063acb
```

### asdf plugins affected (if relevant)

_No response_

Contributor guide

Open the contributing guide

Research direction

Start with the multiple-version guidance at configuration.html#tool-versions and reproduce the behavior using .tool-versions, asdf current, asdf list, and python --version. Trace how asdf selects versions for the Python plugin and compare that behavior with the documented first-to-last fallback order. Done means the implementation and documentation agree and the supplied reproduction behaves accordingly.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, python
Domain
cli, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.