pyenv for Windows 4.0+ (PowerShell rewrite)

pyenv is an amazing tool used to manage multiple versions of python in your machine. Originally ported to Windows by Kiran Kumar Kotari, this fork rewrites pyenv-win entirely in PowerShell 7 for modern Windows compatibility.

• pyenv for Windows 4.0+ (PowerShell rewrite)
  • Introduction
  • pyenv
  • Quick start
  • Commands
  • Installation
  • Validate installation
    • Manually check the settings
  • Usage
  • Tab Completion
  • How to update pyenv
  • FAQ
  • Changelog
  • How to contribute
  • Bug Tracker and Support
  • License and Copyright
  • Author and Thanks

Introduction

pyenv for python is a great tool but, like rbenv for ruby developers, it doesn't directly support Windows. After a bit of research and feedback from python developers, I discovered they wanted a similar feature for Windows systems.

This project was forked from rbenv-win and modified for pyenv. Version 4.0 is a complete rewrite of the original pyenv-win. All legacy VBScript and Batch files have been replaced with PowerShell 7 scripts.

pyenv

pyenv is a simple python version management tool. It lets you easily switch between multiple versions of Python. It's simple, unobtrusive, and follows the UNIX tradition of single-purpose tools that do one thing well.

Quick start

Prerequisite: PowerShell 7+ must be installed. Run pwsh --version to verify.

1. Install pyenv-win in PowerShell:

   irm https://raw.githubusercontent.com/satori-analytics/pyenv-win/master/pyenv-win/install.ps1 | iex

2. Reopen PowerShell

3. Run pyenv --version to check if the installation was successful.

4. Run pyenv install -l to check a list of Python versions supported by pyenv-win

5. Run pyenv install <version> to install the supported version

6. Run pyenv global <version> to set a Python version as the global version

7. Check which Python version you are using and its path:

   > pyenv version
   <version> (set by \path\to\.pyenv\pyenv-win\version)
   

8. Check that Python is working:

   > python -c "import sys; print(sys.executable)"
   \path\to\.pyenv\pyenv-win\versions\<version>\python.exe
   

Commands

commands     List all available pyenv commands
local        Set or show the local application-specific Python version
latest       Print the latest installed or known version with the given prefix
global       Set or show the global Python version
shell        Set or show the shell-specific Python version
install      Install 1 or more versions of Python
uninstall    Uninstall a specific Python version
update       Update the cached version DB from the repository
upgrade      Update pyenv-win itself to the latest version
rehash       Rehash pyenv shims (run this after installing executables)
cache        List, clear, or sync the installer cache
root         Display the root directory where versions and shims are kept
prefix       Display the directory where a Python version is installed
version      Show the current Python version and its origin
versions     List all Python versions available to pyenv
exec         Runs an executable by first preparing PATH so that the selected
             Python version's directory is at the front
which        Display the full path to an executable
whence       List all Python versions that contain the given executable
completions  List available completions for a given command

Installation

Currently we support the following ways, choose any of your comfort:

• PowerShell - default and easiest way
• Pyenv-win zip - manual installation
• Git Commands - adding manual settings

Please see the Installation page for more details.

Validate installation

1. Reopen PowerShell and run pyenv --version
2. Now type pyenv to view its usage

If you are getting "command not found" error, check the note below and manually check the settings.

For Visual Studio Code or another IDE with a built in terminal, restart it and check again.

---

Manually check the settings

The environment variables to be set:

C:\Users\<replace with your actual username>\.pyenv\pyenv-win\bin
C:\Users\<replace with your actual username>\.pyenv\pyenv-win\shims

Ensure all environment variables are properly set with high priority via the GUI:

This PC
   → Properties
      → Advanced system settings
         → Advanced → System Environment Variables...
            → PATH

Note

If you are running Windows 10 1905 or newer, you might need to disable the built-in Python launcher via Start > "Manage App Execution Aliases" and turning off the "App Installer" aliases for Python.

Usage

• To view a list of python versions supported by pyenv windows: pyenv install -l
• To filter the list: pyenv install -l | Select-String 3.12
• To install a python version: pyenv install 3.12.4
  • Note: An install wizard may pop up for some non-silent installs. You'll need to click through the wizard during installation. There's no need to change any options in it, or you can use -q for quiet installation.
  • You can also install multiple versions in one command: pyenv install 3.11.9 3.12.4
• To set a python version as the global version: pyenv global 3.12.4
  • This is the version of python that will be used by default if a local version (see below) isn't set.
  • Note: The version must first be installed.
• To set a python version as the local version: pyenv local 3.12.4
  • The version given will be used whenever python is called from within this folder. This is different than a virtual env, which needs to be explicitly activated.
  • Note: The version must first be installed.
• After (un)installing any libraries using pip or modifying the files in a version's folder, you must run pyenv rehash to update pyenv with new shims for the python and libraries' executables.
  • Note: This must be run outside of the .pyenv folder.
• To uninstall a python version: pyenv uninstall 3.12.4
• To view which python you are using and its path: pyenv version
• To view all the python versions installed on this system: pyenv versions
• Update the list of discoverable Python versions using: pyenv update

Tab Completion

If you installed via the PowerShell installer, tab completion is enabled automatically. Otherwise, add this line to your $PROFILE:

. "$env:PYENV_HOME\completions\pyenv.ps1"

Then restart your shell. You can now press Tab to complete commands and flags, e.g. pyenv inst<Tab> → pyenv install, pyenv install --l<Tab> → pyenv install --list.

How to update pyenv

The simplest way to update pyenv-win is:

pyenv upgrade

This downloads and runs the latest installer, preserving your installed Python versions, cache, and global version setting.

Alternatively:

• If installed via zip
  • Download the latest pyenv-win.zip from the Releases page
  • Extract it and replace the pyenv-win folder under %USERPROFILE%\.pyenv\
• If installed via Git, navigate to the location where you installed pyenv, usually %USERPROFILE%\.pyenv\pyenv-win, and run git pull

Note

pyenv update only refreshes the Python versions database. To update pyenv-win itself, use pyenv upgrade.

FAQ

Please see the FAQ page.

Changelog

Please see the Changelog page.

How to contribute

• Fork the project & clone locally.
• Create an upstream remote and sync your local copy before you branch.
• Branch for each separate piece of work using the naming convention: feature/, fix/, ci/, test/, or doc/ prefix (e.g. feature/add-caching, fix/shim-regression).
• Do the work, write good commit messages. It's good practice to write test cases.
• Test the changes by running Invoke-Pester ./tests
• Push to your origin repository.
• Create a new Pull Request in GitHub.

Bug Tracker and Support

• Please report any suggestions, bug reports, or annoyances with pyenv-win through the GitHub bug tracker.

License and Copyright

• pyenv-win is licensed under 2026

Author and Thanks

pyenv-win was originally created by Kiran Kumar Kotari. This fork is maintained by Nikolas Demiridis, Satori Analytics and Contributors.