virtualenv-pyenv 0.3.0

A virtualenv Python discovery plugin for pyenv-installed interpreters

virtualenv-pyenv

A virtualenv Python discovery plugin for pyenv–installed interpreters

Installation

pip install virtualenv-pyenv

Usage

The Python discovery mechanism can be specified by:

• the CLI option --discovery:

  virtualenv --discovery pyenv -p 3.10 testenv
  

• the environment variable VIRTUALENV_DISCOVERY:

  export VIRTUALENV_DISCOVERY=pyenv
  virtualenv -p 3.10 testenv
  

• the config option discovery:

  [virtualenv]
  discovery = pyenv
  

  virtualenv -p 3.10 testenv
  

• the virtualenvwrapper environment variable VIRTUALENVWRAPPER_VIRTUALENV_ARGS:

  export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--discovery=pyenv'
  mkvirtualenv -p 3.10 testenv
  

Python Specifier Format

The plugin supports two specifier formats informally called “pyenv-style” and “virtualenv-style”.

The version part of both specifier formats can contain either two (major.minor) or three (major.minor.patch) components. When a two–component version is specified, the latest installed final patch release is selected, ignoring pre–/dev–releases. When a three–component version is specified, the exact final release is selected, ignoring pre–/dev–releases. The pre–/dev–release version is installed only if it is explicitly requested.

installed	requested	selected
3.9.5; 3.9.17	3.9	3.9.17
3.9.5; 3.9.17	3.9.5	3.9.5
3.9.5; 3.9.17	3.9.0	—
3.12-dev; 3.12.0b3	3.12	—
3.12-dev; 3.12.0b3	3.12.0	—
3.12-dev; 3.12.0b3	3.12-dev	3.12-dev
3.12-dev; 3.12.0b3	3.12.0b3	3.12.0b3

pyenv–style

The same format as used by pyenv (pyenv install --list).

• a final version with 2 version components: 3.11
• a final version with 3 version components: 3.11.2
• a pre–release version: 3.13.0a4, 3.12.0b3, 3.11.0rc1
• a dev version: 3.13-dev

virtualenv–style

The same format as used by virtualenv (docs). A subset of this format is used by tox (docs).

• a relative or absolute path: /path/to/bin/python (it can be any Python interpreter, not only installed by pyenv)
• a final version with 2 version components: 311, py311, py3.11, python311, cpython3.11, python3.11-32, py311-64
• a final version with 3 version components: py3.11.2, python3.11.2, cpython3.11.2, python3.11.2-32, py3.11.2-64

Limitations

• Only CPython is supported at the moment.
• The architecture part (-32/-64) of a specifier is ignored. For example, all of the following specifiers match any installed CPython 3.8.1 regardless of the architecture: python3.8.1, python3.8.1-32, python3.8.1-64.
• pyenv-win is not supported.

Internals

virtualenv-pyenv does not rely on pyenv to discover Python interpreters, that is, it never calls any pyenv command and does not require pyenv to be in PATH. Instead, the plugin uses pyenv-inspect library, which, in turn, inspects $PYENV_ROOT/versions directory contents.