As a Python developer, managing multiple versions of Python and their associated packages can quickly become a headache, especially when working on different projects with varying dependencies. This is where virtual environments come into play, allowing you to create isolated Python environments for each project and ensuring smooth development without conflicts. In this post, we'll explore how to install pyenv and pyenv-win on Windows 11, powerful tools that simplify the process of managing Python versions and virtual environments. macOS users have an alternative option with direnv, which is also considered in this blog post.

Windows

Step 1: Install pyenv. pyenv is a Python version management tool that allows you to install and switch between multiple Python versions seamlessly. To install pyenv on Windows 11, follow these steps:

  1. Open PowerShell as an administrator.
  2. Run the following command to install pyenv:
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
  1. After the installation completes, restart the PowerShell

Step 2: Install pyenv-win. pyenv-win is a Python version management extension for Windows that works seamlessly with pyenv. To install pyenv-win, run the following command in PowerShell:

pyenv install pyenv-win

Step 3: Install Python Versions. With pyenv and pyenv-win installed, you can now install different Python versions. To see a list of available Python versions, run:

pyenv install --list

To install a specific version, for example, Python 3.11.5, run:

pyenv install 3.11.5

Step 4: Create and Manage Virtual Environments. Virtual environments are isolated Python environments that allow you to install and manage packages specific to a project without affecting the global Python installation. With pyenv-win, you can create and manage virtual environments effortlessly.

To create a new virtual environment with Python 3.11.5, run the following:

pyenv-venv install 3.11.5 .ultralitics-env

Before installing any Python packages, the virtual environment needs to be activated. To activate:

pyenv-venv activate .ultralitics-env

After executing this command, you should see that the respective env is activated, and there's an indication of that in the CMD (see in green below):

In case you forgot the env name, you can list them using this command:

pyenv-venv list envs

To deactivate the virtual environment, run:

pyenv-venv deactivate

Step 5: Use Virtual Environments. The virtual environment is initially empty. You can check it by running a pip list (it will only list pip among the packages installed, which is expected). With an active virtual environment, you can install project-specific packages using pip as you normally would. For example, to install the Flask web framework:

pip install flask
The packages will be installed within the isolated virtual environment, preventing conflicts with other projects or the global Python installation.
 

macOS

While pyenv and pyenv-win are excellent tools for managing Python versions and virtual environments on Windows, macOS users have an alternative option with direnv. This powerful tool allows you to automatically load and unload environment variables based on your current working directory, making it a convenient solution for managing project-specific virtual environments. This page lists an installation guide for macOS and other OS types, including different distributions of Linux.
Step 1: Install direnv. First, you'll need to install direnv using a package manager like Homebrew:
brew install direnv
Step 2: Set up direnv. After installation, you need to update your shell configuration.
If you use 'bash', add the following line at the end of the ~/.bashrc file:  
eval "$(direnv hook bash)"
If you use 'zsh', add the following line at the end of the ~/.zshrc file:  
eval "$(direnv hook zsh)"
If you use 'Oh my zsh' (as I do), add direnv to the plugins array in your  ~/.zshrc file:  
plugins=(... direnv)
Step 3: Create a Virtual Environment. Navigate to your project directory and create a new virtual environment using your preferred tool (e.g., virtualenv, conda). For example, with virtualenv:
python -m venv .venv
Step 4: Configure direnv Create an .envrc file in your project directory and add the following line to automatically activate the virtual environment when you navigate to the project directory:
layout_python-venv python3 .venv/bin/python
Step 5: Allow direnv Run the following command to allow direnv to load the .envrc file:
direnv allow
From now on, whenever you navigate to your project directory, direnv will automatically activate the associated virtual environment. When you leave the directory, the environment will be deactivated, ensuring a clean and isolated development environment for each project.
With direnv, you don't directly install different Python versions. Instead, direnv relies on your system's Python installation to create and manage virtual environments. However, you can use direnv in conjunction with a Python version manager like pyenv to seamlessly switch between different Python versions for each project
 Here's how you can set it up:
  • Install pyenv:
brew update
brew install pyenv
  • Install direnv (as described above)
  • Set it up
  • Create a new project directory (or use an existing project)
  • Install a specific Python version with pyenv. Use pyenv to install the desired Python version. For example, to install Python 3.11.5:
pyenv install 3.11.5
  • Create a virtual environment. Within the project directory, create a new virtual environment using the installed Python version:
pyenv virtualenv 3.11.5 .ultralitics-env
  • Configure direnv. Create an .envrc file in your project directory and add the following lines (this line tells direnv to set up the environment using the Python version specified by pyenv):
layout_python python3 "$(pyenv root)/versions/$(pyenv version-name)/bin/python"
  • Allow direnv. Run the following command to allow direnv to load the .envrc file:
 direnv allow

Now, whenever you navigate to your project directory, direnv will automatically activate the associated virtual environment and load the Python version specified by pyenv. When you leave the directory, the environment will be deactivated. To switch to a different Python version for another project, simply repeat bullet points 3-7 with the desired Python version. Note that direnv doesn't require any additional plugins to work with pyenv. It seamlessly integrates with the Python version manager by leveraging the system's Python installation and the virtual environments created by pyenv.

By combining direnv and pyenv, you can manage both virtual environments and Python versions efficiently, ensuring a clean and isolated development environment for each project.

 
Summary
In this blog post, we explored how to install pyenv and pyenv-win on Windows 11 and direnv for macOS, powerful tools for managing Python versions and virtual environments. We covered the installation process, creating and managing virtual environments, and using virtual environments for isolated package installations. By leveraging these tools, you can streamline your Python development workflow, ensure project dependency isolation, and easily switch between Python versions as needed. Say goodbye to the hassle of managing Python environments manually and embrace a more efficient and organized development experience.
 
Like the article and enjoyed reading it? Buy me a coffee!
 
Happy coding ;)