Managing virtual environments in Python

Managing Python versions and dependencies often feels like an "alphabet soup" of tools. Here is how to organize pyenv, pyenv-virtualenv, and pipenv without them clashing.

---

The Toolset

• Pyenv → Manages Python Versions. It lets you switch between Python 3.8, 3.11, or 3.12 globally or per folder.
• Pyenv-virtualenv → An extension for Pyenv that manages Named Virtual Environments.
• Pipenv → A Higher-level Manager. It handles both the virtual environment and package dependencies using a Pipfile (replacing requirements.txt).

---

Recommended Workflows

Option 1: The "Manual" Approach (Pyenv + Pyenv-Virtualenv)

Best for: Quick scripts, simple tools, or developers who prefer full control over pip.

1. Install Python: pyenv install 3.11.5
2. Create Environment: pyenv virtualenv 3.11.5 my-project-env
3. Local Link: pyenv local my-project-env
   • Result: Every time you enter this folder, your terminal automatically switches to my-project-env.
4. Manage Deps: Use pip install and manually maintain a requirements.txt.

Option 2: The "Modern" Approach (Pyenv + Pipenv)

Best for: Production applications and collaborative projects where dependency locking is vital.

1. Install Python: pyenv install 3.11.5
2. Initialize Pipenv: pipenv install --python 3.11.5
   • Note: You do not need to run pyenv local first. Pipenv will communicate with Pyenv to find the correct version.
3. Activate: pipenv shell
4. Manage Deps: Use pipenv install <package>. This automatically updates your Pipfile and Pipfile.lock.

---

Critical Disclaimers

[!CAUTION]
Avoid "Nesting" Environments: Never run pipenv install while a pyenv-virtualenv is already active. This can cause Pipenv to install packages into the wrong environment or create a "ghost" environment that is difficult to debug. Pick one manager per project.

[!IMPORTANT]
Storage Locations: > * pyenv-virtualenv stores environments in ~/.pyenv/versions/.

• pipenv stores them in a hidden central folder (usually ~/.local/share/virtualenvs/).
• Pro Tip: To keep Pipenv environments inside your project folder (like .venv), set export PIPENV_VENV_IN_PROJECT=1 in your shell profile.

---

Comparison at a Glance

Feature	Pyenv-Virtualenv	Pipenv
Primary Goal	Isolation	Dependency Management
Tracking	None (Manual requirements.txt)	Deterministic (Pipfile.lock)
Activation	Automatic via .python-version	Manual via pipenv shell
Complexity	Low	Medium

---

Final Rule of Thumb

• Use Pyenv + Pipenv if you need a "lockfile" to ensure your teammates have the exact same package versions as you.
• Use Pyenv + Pyenv-Virtualenv if you just want a clean, isolated sandbox for a project and don't care about strict version locking.

Hopefully, this article helps someone avoid making the same mistakes I did. If you like it or hate it, leave a comment. Got anything to add? Be my guest. Keep your opinion to yourself. Later, skater.