How to Use `pyenv` to Manage Multiple Python Versions (with examples)

pyenv is a powerful tool designed to help developers easily manage multiple Python versions on a single machine. By providing a simple interface for switching between different Python environments, pyenv simplifies workflows for developers who work across multiple projects requiring different Python setups. It alleviates the complexities and potential conflicts that arise from maintaining various Python versions on the same system. As a handy command-line utility, pyenv supports installing, uninstalling, and switching between Python versions, making it an essential tool for Python developers.

Use Case 1: Listing All Available Commands

Code:

pyenv commands

Motivation: For anyone new to pyenv or those looking to explore the full range of functionalities offered by the tool, listing all available commands is an ideal starting point. It provides a comprehensive look at all the operations pyenv can perform, ensuring users are aware of the different ways they can leverage the tool.

Explanation: The command pyenv commands does not take any additional arguments. It simply instructs pyenv to output a list of all the commands it supports, providing a comprehensive overview to the user.

Example Output:

commands
completions
exec
global
hooks
...

Use Case 2: Listing Installed Python Versions

Code:

pyenv versions

Motivation: Before switching to or managing Python versions, it’s crucial to know what versions are already installed on the machine. This command helps in identifying which Python versions are currently available under the ${PYENV_ROOT}/versions directory, aiding in better version management.

Explanation: The command pyenv versions calls upon pyenv to scan its versions directory and list all available Python installations, effectively displaying what is ready for use on the local system.

Example Output:

  2.7.10
  3.6.9
* 3.8.5 (set by /home/user/.pyenv/version)

Use Case 3: Listing Python Versions Available for Installation

Code:

pyenv install --list

Motivation: When you need to utilize a specific Python version that you haven’t installed yet, knowing what’s available upstream is the first step. This command lists all Python versions you can install via pyenv, helping you comply with project requirements or test your code against different Python releases.

Explanation: The pyenv install --list command fetches and displays a list of all Python versions that can be installed. The --list argument specifies that a list of installable versions from upstream sources should be displayed.

Example Output:

2.1.3
2.2.3
2.3.7
...
3.9.0
3.9.1

Use Case 4: Installing a Python Version

Code:

pyenv install 2.7.10

Motivation: To run applications or projects that require a particular Python version, you first need to install it on your system. This command allows you to add a specific version to your Python environment set up by pyenv.

Explanation: The pyenv install command requires a specific version number as an argument. In this case, 2.7.10 is the desired Python version to be installed.

Example Output:

Downloading Python-2.7.10.tar.xz...
-> https://www.python.org/ftp/python/2.7.10/Python-2.7.10.tar.xz
Installing Python-2.7.10...

Use Case 5: Uninstalling a Python Version

Code:

pyenv uninstall 2.7.10

Motivation: Over time, some Python versions may become obsolete or unnecessary. This command helps clean up your Python environment by removing a specific version, thus freeing system resources and simplifying version management.

Explanation: The pyenv uninstall command takes a specific Python version as an argument, which is 2.7.10 in this context, instructing pyenv to remove it from the ${PYENV_ROOT}/versions directory.

Example Output:

pyenv: remove /home/user/.pyenv/versions/2.7.10? y

Use Case 6: Setting a Global Python Version

Code:

pyenv global 2.7.10

Motivation: When working on a system-wide project or when preferring a default Python version across all shell sessions, setting a global Python version is essential. This command designates a Python version as the global default, affecting all directories unless specifically overridden.

Explanation: This command uses global as its operation and requires a specific version number, 2.7.10, to set it as the default Python version system-wide.

Example Output:

Use Case 7: Setting a Local Python Version

Code:

pyenv local 2.7.10

Motivation: Projects often require different Python versions, and setting a directory-specific version helps isolate and manage these requirements effectively. The pyenv local command ensures that a specific Python version is used within a particular directory, propagating to any subdirectories.

Explanation: The pyenv local command takes a specific Python version, 2.7.10, and makes it applicable only to the current directory and any subdirectories, helping to manage project-specific dependencies.

Example Output:

Conclusion:

pyenv is an indispensable tool for developers who frequently engage with multiple Python environments. Using pyenv, developers can easily switch between different Python versions to suit project-specific needs, test code compatibility with various Python releases, and maintain clean and organized development environments. Through the examples provided, it’s clear how pyenv streamlines Python version management with commands that are both intuitive and powerful. Whether listing available versions, installing a new one, or specifying which version to use globally or locally within projects, pyenv empowers developers to take control of their Python environments with ease.