bug: multiple version selection does not work as documented
- 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
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