explaingit

pyenv/pyenv-virtualenv

6,729ShellAudience · developerComplexity · 2/5Setup · easy

TLDR

A pyenv plugin that creates isolated Python environments per project and auto-activates them when you enter a project folder, no manual activate commands needed.

Mindmap

mindmap
  root((pyenv-virtualenv))
    What it does
      Isolated Python environments
      Auto-activation on folder entry
    Key features
      Per-project environments
      Auto activate deactivate
    Compatibility
      Python 3 venv
      virtualenv conda miniconda
    Installation
      Homebrew macOS
      Clone into pyenv plugins
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Create an isolated Python environment for each project so packages installed for one project never break another.

USE CASE 2

Set up auto-activation so the correct Python version and environment load automatically when you enter a project folder.

USE CASE 3

Manage conda and Miniconda environments through the same pyenv interface alongside standard virtual environments.

Tech stack

ShellPython

Getting it running

Difficulty · easy Time to first run · 30min

Requires pyenv to be installed first, then add one line to your shell startup file to enable auto-activation.

No explicit license is stated in the repository description.

In plain English

pyenv-virtualenv is a plugin for pyenv, the tool that lets you install and switch between multiple Python versions on a single computer. While pyenv handles which version of Python is active, pyenv-virtualenv goes a step further by managing isolated Python environments for individual projects. An isolated environment has its own copy of Python and its own set of installed packages, so changes made for one project cannot break another. To create a new environment, you run a single command and specify which Python version and what name you want. The environment is stored inside pyenv's own directory structure so it stays out of your project folder. You can list all your environments, switch to one by name, and delete one when you no longer need it. One convenient feature is auto-activation. If you add a short line to your shell configuration file, pyenv-virtualenv will automatically switch to the right environment whenever you navigate into a project folder that has a configuration file naming which environment to use. When you leave that folder, the environment is automatically deactivated. This means you generally do not have to remember to run any activate commands manually. The plugin works with the standard Python virtual environment tools for Python 3, with the older virtualenv package for Python 2 and older setups, and also with Anaconda and Miniconda conda environments. It detects which tool is available and uses the appropriate one. Installation on macOS through Homebrew is a single command. On other systems, it involves cloning the repository into pyenv's plugins directory and adding one line to your shell startup file. The plugin works on any Unix-like system including Linux and macOS.

Copy-paste prompts

Prompt 1
How do I install pyenv-virtualenv on macOS via Homebrew and set up auto-activation so my project's environment loads when I cd into the folder?
Prompt 2
Using pyenv-virtualenv, show me the commands to create a Python 3.11 virtual environment named 'myproject', activate it, and install packages into it.
Prompt 3
How do I configure pyenv-virtualenv to automatically switch environments when entering different project directories on Linux?
Prompt 4
What is the difference between using pyenv-virtualenv with Python 3 venv versus the older virtualenv package, and when does each get used?
Open on GitHub → Explain another repo

← pyenv on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.