[Python] Managing Python Versions with venv and pyenv: The Perfect Combination

One of the most common challenges in Python development is dealing with multiple Python versions and package conflicts. Different projects may require different Python versions, and team members might encounter unexpected errors due to environmental inconsistencies. By using venv and pyenv together, you can effectively manage Python versions and virtual environments, ensuring a seamless development workflow.

In this post, we’ll explore the concepts and roles of venv and pyenv, and walk through how to use them together step by step.

Table of Contents　

Understanding the Roles of venv and pyenv

What is venv?

venv is a built-in Python module that allows you to create isolated virtual environments for different projects. It helps manage dependencies and avoid conflicts between packages.

Key Features:

Isolates dependencies for each project
Manages environments within the same Python version

[Python] Using ‘venv’: Efficiently Manage Multiple Projects Without Conflicts

What is pyenv?

pyenv is a tool for managing multiple Python versions. It allows you to easily install different versions of Python and specify which version to use globally or per project.

Key Features:

Installs and switches between multiple Python versions
Assigns specific Python versions to different projects
Prevents version conflicts

Why Use venv and pyenv Together?

pyenv controls Python versions, while venv creates virtual environments within those versions. By combining both, you achieve complete isolation for Python version management and package dependencies.

Setting Up pyenv and venv

Installing and Configuring pyenv

Step 1: Install pyenv

The installation method depends on your operating system. Follow the instructions in the post below:

[Python] pyenv: 다양한 Python 버전을 간편하게 관리하는 방법

Step 2: Install the Required Python Versions

pyenv install 3.8.5
pyenv install 3.10.2

Step 3: Verify Installed Python Versions

pyenv versions

Step 4: Set the Python Version for a Project

pyenv local 3.8.5

Setting Up venv

Step 1: Create a Virtual Environment

Once the Python version is set using pyenv, create a virtual environment for the project:

python -m venv venv

Step 2: Activate the Virtual Environment

For macOS/Linux:

source venv/bin/activate

For Windows:

venv\Scripts\activate

Step 3: Deactivate the Virtual Environment

deactivate

Using pyenv and venv Together

Setting Python Version and Virtual Environment for a Project

Follow these steps to use pyenv and venv together.

Step 1: Set the Python Version for a Project

Run the following command in the project folder to lock the Python version to 3.11.2:

pyenv local 3.11.2

Step 2: Create a Virtual Environment

python -m venv [venv_project_name]

Step 3: Activate the Virtual Environment and Install Dependencies

source venv_project_name/bin/activate  
pip install requests flask

Step 4: Save Dependencies

pip freeze > requirements.txt

Managing Multiple Project Environments

With pyenv and venv, you can easily manage different Python versions and dependencies for multiple projects.

Example:

Project A

Python 3.10.2
Django 3.2

Project B

Python 3.8.5
Flask 2.0

Setting Up Project A

cd project_a
pyenv local 3.10.2
python -m venv venv
source venv/bin/activate
pip install django==3.2

Setting Up Project B

cd project_b
pyenv local 3.8.5
python -m venv venv
source venv/bin/activate
pip install flask==2.0

Troubleshooting

Issue 1: Installed Python Version Is Not Recognized

Solution 1: Rehash pyenv

pyenv rehash

Solution 2: Check PATH Configuration

If running pyenv version results in an error, ensure the system PATH includes the correct pyenv directories.

For Windows users, add the following paths to the system environment variables:

%USERPROFILE%\anaconda3\Lib\site-packages\pyenv-win\bin
%USERPROFILE%\anaconda3\Lib\site-packages\pyenv-win\shims

Issue 2: A Different Python Version Is Activated in the Virtual Environment

Cause: pyenv and venv may have conflicting settings.
Solution:

Explicitly set the Python version using pyenv local.
Recreate the virtual environment with the correct Python version.

Issue 3: Cannot Activate venv in Windows PowerShell

If you encounter the following error:

"cannot be loaded because the execution of scripts is disabled on this system."

Solution: Change PowerShell Execution Policy

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine

By combining venv and pyenv, you can efficiently manage Python versions and package dependencies. This approach is particularly beneficial for developers working on multiple projects or collaborating in a team environment. If you want to streamline your Python development workflow, start implementing this setup today!