Skip to content

Effortlessly Managing Python Versions: A Comprehensive Guide


Managing Python Versions with pyenv

Managing multiple versions of Python can be a challenge, especially when working on projects that require specific versions or when you want to try out the latest features. However, with the help of pyenv, this process becomes much easier. In this tutorial, we will explore how to effectively manage Python versions using pyenv, allowing you to switch between different versions effortlessly.

Why Use pyenv?

Before we dive into the installation and usage of pyenv, let’s understand why this tool is beneficial.

Why Not Use System Python?

By default, most operating systems come with a pre-installed version of Python, often referred to as “System Python.” While this version is readily available and accessible, it has limitations. System Python is usually managed by the operating system and can cause complications when working on projects that require specific versions or when trying out the latest features.

For example, running python -V in your terminal will likely display the version of System Python installed. However, this may not be the version you need for your project. Additionally, installing packages or libraries into System Python requires administrative privileges, such as running sudo pip install.

Using System Python directly can be problematic, especially when working on multiple projects with different Python version requirements. That’s where pyenv comes in.

Why Use pyenv?

pyenv is a powerful tool that allows for the easy management of multiple Python versions on your system. Some of the benefits of using pyenv include:

  • Flexibility: With pyenv, you can easily switch between different Python versions, depending on your project requirements.
  • Isolation: pyenv creates a separate environment for each Python version, ensuring that your projects remain isolated from one another.
  • Testing: pyenv makes it simple to test your code across different Python versions, ensuring compatibility and identifying any version-specific bugs.
  • Access to Pre-release Versions: pyenv allows you to install and test pre-release versions of Python, giving you a chance to explore and experiment with new features before they are officially released.

Now that we understand the benefits of using pyenv, let’s proceed with the installation process.

Installing pyenv

The installation process for pyenv may vary depending on your operating system. Here, we will cover the general steps to get pyenv up and running.

Build Dependencies

Before installing pyenv, there are a few dependencies that need to be in place. These dependencies include:

  • gcc or clang: Make sure you have a C compiler installed on your system.
  • make: This is necessary for building pyenv.
  • git: pyenv is managed through Git, so having Git installed is essential.

Ensure that these dependencies are installed before proceeding with the installation of pyenv.

Using the pyenv-installer

The easiest method to install pyenv is by using the pyenv-installer script. Here’s how to do it:

  1. Open your terminal and run the following command to download and install pyenv:

    Terminal window
    $ curl | bash
  2. After the installation is complete, add pyenv to your shell by adding the following lines to your shell configuration file (e.g., .bashrc, .zshrc):

    Terminal window
    $ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
    $ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc

    Make sure to replace .bashrc with the appropriate configuration file for your shell, if necessary.

  3. Reload your shell configuration by running:

    Terminal window
    $ source ~/.bashrc

    Again, replace .bashrc with the appropriate configuration file if you’re using a different shell.

  4. Verify that pyenv is installed by running the following command:

    Terminal window
    $ pyenv --version

    This should display the version information, indicating that pyenv has been successfully installed.

Congratulations! You have successfully installed pyenv on your system. Now, let’s explore how to use pyenv to install and manage Python versions.

Using pyenv to Install Python

Once pyenv is installed, you can start installing multiple versions of Python using the tool. Let’s walk through the process step by step.

Installation Location

By default, pyenv installs Python versions into the ~/.pyenv/versions directory on your system. This ensures that each Python version remains isolated and accessible through pyenv. When installing a new Python version, you can specify the installation directory by using the install command.

For example, to install Python 3.9.2, run the following command:

Terminal window
$ pyenv install 3.9.2

After the installation is complete, you can check the installed Python versions with the versions command:

Terminal window
$ pyenv versions

This will display a list of all the Python versions available on your system.

Using Your New Python

Now that you have installed a new Python version using pyenv, you can start using it by setting it globally or locally.

  • Global Python version: To set a global Python version, run the following command:

    Terminal window
    $ pyenv global 3.9.2

    This will set the specified Python version as the default version across all your projects.

  • Local Python version: To set a Python version locally in a specific directory, navigate to the directory and run the following command:

    Terminal window
    $ pyenv local 3.9.2

    This will set the specified Python version for that particular directory and its subdirectories.

Now you can run Python commands or scripts using the respective pyenv-managed Python version.

Exploring pyenv Commands

pyenv provides various commands to manage Python versions effectively. Here are some essential commands to help you navigate pyenv:

  • install: Installs a specific version of Python.
  • versions: Lists all the installed Python versions on your system.
  • which: Displays the full path of the currently active Python version.
  • global: Sets the global Python version to be used across all projects.
  • local: Sets the local Python version for a specific directory.
  • shell: Sets the preferred shell environment for pyenv.

Feel free to explore other pyenv commands that suit your specific needs.

Specifying Your Python Version

pyenv allows you to specify a Python version for individual projects or directories. This functionality is particularly useful when working on projects that require specific Python versions. To specify a Python version for a project, navigate to the project directory and create a .python-version file containing the desired Python version (e.g., 3.9.2). When pyenv encounters this file, it will automatically set the specified Python version for the project.

Virtual Environments and pyenv

Python’s virtual environments are an excellent way to isolate project dependencies and maintain different Python environments for various projects. pyenv seamlessly integrates with virtual environments, allowing you to create and activate them easily.

Creating Virtual Environments

To create a virtual environment, use the venv module or any other virtual environment tool, such as virtualenv or pipenv. After creating the virtual environment, navigate to the project directory and set the local Python version to the virtual environment’s Python version:

Terminal window
$ pyenv local <virtual_env_python_version>

This ensures that the specified virtual environment’s Python version is used for the project.

Activating Your Versions

Activating different Python versions and virtual environments can be tedious. However, pyenv simplifies this process by automatically activating the appropriate Python version when you navigate to a project directory with pyenv set up.

Working With Multiple Environments

With pyenv, managing multiple Python environments becomes effortless. You can install different Python versions using pyenv and switch between them easily, depending on the requirements of your projects. This flexibility allows you to work on various projects simultaneously, each with its own version of Python and set of dependencies.

Activating Multiple Versions Simultaneously

In some cases, you may need to activate multiple Python versions simultaneously, either for experimentation purposes or to test compatibility. pyenv provides the ability to activate multiple versions using the pyenv local or pyenv shell commands.

For example, to activate Python 3.9.2 and Python 3.8.8 at the same time, navigate to the project directory and run the following command:

Terminal window
$ pyenv local 3.9.2 3.8.8

This will activate both Python versions, allowing you to switch between them as needed.


In this tutorial, we explored the powerful tool pyenv for managing multiple Python versions. We discussed the benefits of using pyenv and walked through the installation process. We also learned how to install and use different Python versions, create virtual environments, and switch between environments effortlessly.

pyenv simplifies the process of managing Python versions, allowing you to focus on your projects rather than worrying about compatibility issues. With pyenv, you can easily test your code across different Python versions, work on multiple projects simultaneously, and stay up to date with the latest Python releases.

Now that you have a solid understanding of pyenv, you’re ready to take control of your Python development environment and maximize your productivity.

Further Reading:

Remember to save your progress by marking this article as completed. Happy Python coding!