Centralising the python Virtual Environment Management with pyenv and plugin

Best practice for Python development is to create virtual environments, ideally one per project, but this often leads to scattered environments across your system. With pyenv and its plugin pyenv-virtualenv, you can centralize all environments in one location. Pyenv is a powerful tool for managing multiple Python versions, while pyenv-virtualenv extends it by enabling seamless virtual environment creation and management. This combination keeps your Python environments well-organized, ensures they are tied to specific Python versions, and even allows automatic activation based on the project directory, making development simpler and more efficient. Here's how to set it up:


Install and Configure pyenv and pyenv-virtualenv

1. Install System Package for Virtual Environments

First, install the required venv package for your system's default Python version:

# Get the default Python version from the system
PYTHON_VERSION=$(python3 --version | awk '{print $2}' | cut -d. -f1,2)

# Install the appropriate package
sudo apt install -y python${PYTHON_VERSION}-venv

2. Clone pyenv and pyenv-virtualenv

Clone both pyenv and the pyenv-virtualenv plugin:

# Clone pyenv
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

# Clone pyenv-virtualenv plugin
git clone https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

3. Update Shell Configuration

Modify your shell configuration files (~/.bashrc, ~/.profile, or ~/.bash_profile) to include the necessary environment variables and initialization commands. Use the following commands based on your shell configuration:

Add to ~/.bashrc:
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc 
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc 
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
Add to ~/.profile (if ~/.bashrc is not sourced):
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init -)"' >> ~/.profile
Add to ~/.bash_profile (alternative to ~/.bashrc):
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(pyenv init -)"' >> ~/.bash_profile

4. Reload Shell

To apply the changes, reload your shell:

source ~/.bashrc  # Or source the relevant file, e.g., ~/.profile or ~/.bash_profile

Using the pyenv to manage the environment

Create a Virtual Environment

Use pyenv virtualenv to create a new virtual environment tied to a specific Python version:

pyenv install 3.11.6  # Install the desired Python version
pyenv virtualenv 3.11.6 myenv  # Create a virtual environment named 'myenv'
List Virtual Environments

View all available virtual environments:

pyenv virtualenvs
Activate a Virtual Environment

Manually activate a virtual environment:

pyenv activate myenv
Deactivate a Virtual Environment

Deactivate the currently active virtual environment:

pyenv deactivate
Delete a Virtual Environment

Remove a virtual environment:

pyenv uninstall myenv
Set a Local Environment AutoActivate

To associate a virtual environment with a specific project directory, navigate to the project and set the local environment:

cd /path/to/project
pyenv local myenv

This creates a .python-version file in the project directory. The virtual environment will auto-activate whenever you enter the directory.


Verification

  • Verify the installed pyenv version: bash pyenv --version
  • Verify pyenv-virtualenv integration: bash pyenv virtualenvs