what is the difference between `pyenv global x.y.z` and `pyenv shell x.y.z`?

Question

I installed:

$ pyenv install 3.7.3
$ pyenv versions
system *
3.7.3
$

Then to switch from system (Python 3.8.5) to 3.7.3 I can use both global and shell:

$ pyenv global 3.7.3
$ python3 --version
3.7.3
$ 
$ pyenv global system
$ python3 --version
3.8.5
$ 


$ pyenv shell 3.7.3
$ python3 --version
3.7.3
$ 
$ pyenv shell system
$ python3 --version
3.8.5
$ 

What is the difference between the switch using global and the one using pyenv shell ?

Note: If we mix pyenv shell and pyenv global we get strange results

on my ~/.bashrc:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
if command -v pyenv 1>/dev/null 2>&1; then
  eval "$(pyenv init --path)"
  eval "$(pyenv init -)"
  eval "$(pyenv virtualenv-init -)"
fi

Geosynclinal

The pyenv commands are actually quite well explained in the documentation: github.com/pyenv/pyenv/blob/master/COMMANDS.md – Baseburner

Answer 1

pyenv global reads/writes the ~/.python-version file. In the absence of any other clues, pyenv uses this file to determine which python version to use.

pyenv shell sets the PYENV_VERSION environment variable for that shell. AKA it's equivalent to export PYENV_VERSION=3.9.1 for example. That means that this is temporary - when the shell exits, this command is lost until next time.

You can see from the docs how the python version is chosen:

The PYENV_VERSION environment variable (if specified). You can use the pyenv shell command to set this environment variable in your current shell session.

The application-specific .python-version file in the current directory (if present). You can modify the current directory's .python-version file with the pyenv local command.

The first .python-version file found (if any) by searching each parent directory, until reaching the root of your filesystem.

The global $(pyenv root)/version file. You can modify this file using the pyenv global command. If the global version file is not present, pyenv assumes you want to use the "system" Python. (In other words, whatever version would run if pyenv weren't in your PATH.)

Stan