# pyenv-win: Managing Multiple Python Versions on Windows

> pyenv-win ports the pyenv version manager to Windows. It targets developers who need to switch between Python interpreters per project, and it installs through PowerShell, pip, or Chocolatey. The command surface is small, but the shim layer and rehash behaviour are where the real constraints live.

**pyenv-win/pyenv-win** — pyenv for Windows. 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.

- Repository: https://github.com/pyenv-win/pyenv-win
- Website: https://pyenv-win.github.io/pyenv-win
- Stars: 7,406 · Forks: 593
- Language: VBScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/pyenv-win-pyenv-win

## What pyenv-win solves on Windows and who it is for

Python on Windows has no native equivalent of the pyenv workflow. The README states that pyenv for Python is a great tool but, like rbenv for Ruby developers, it does not directly support Windows. pyenv-win fills that gap. It was forked from rbenv-win and modified for pyenv, and the README describes it as fairly mature thanks to contributions.

The audience is narrow and specific. Developers who keep several Python interpreters installed at once, and who want a project folder to select its own interpreter without an activation step, are the primary users. The README draws that distinction directly: a local version is used whenever python is called from within this folder, which is different from a virtual environment that needs to be explicitly activated. If your workflow already depends on virtual environments per project, pyenv-win changes the interpreter, not the package set. It is a version manager, not a dependency manager.

## How the shim and version-resolution mechanism works

pyenv-win installs interpreters under a per-user directory and puts two entries on PATH: a bin directory and a shims directory. The README lists both paths with the placeholder C:\Users\<replace with your actual username>\.pyenv\pyenv-win\bin and the matching shims path. The shims directory is what makes version switching transparent. When you call python, the shim intercepts the call, resolves which version applies, and forwards to the real executable.

Resolution follows a precedence order visible in the commands. A shell-specific version set with pyenv shell applies to the current shell. A local version set with pyenv local applies to the current folder. A global version set with pyenv global is the fallback when no local version is set. The README's own example output shows the origin of the decision: pyenv version prints the version followed by (set by \path\to\.pyenv\pyenv-win\.python-version). That file is the local marker.

The consequence is that shims are generated artifacts. After installing or uninstalling libraries with pip, or after modifying files in a version's folder, the README says you must run pyenv rehash to update pyenv with new shims for the python and libraries' executables. A newly installed console script that is not visible on PATH is usually a missing rehash, not a broken install.

## Installing pyenv-win and setting a first interpreter

The README lists several installation routes: PowerShell, Git commands, a pyenv-win zip, Python pip, and Chocolatey. The PowerShell path is described as the easiest. It downloads a script and runs it in the current session.

```pwsh
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"
```

After the script finishes, close and reopen PowerShell so the environment variables take effect, then confirm the tool is on PATH.

```bash
pyenv --version
```

If that returns a command-not-found error, the README points to a manual settings check. The two directories that must be on PATH are the bin and shims folders under your user profile. The README also notes that on Windows 10 1905 or newer you might need to turn off the built-in Python launcher through Start, then Manage App Execution Aliases, disabling the App Installer aliases for Python. That step is easy to miss and produces confusing results when the Store alias wins the PATH race.

Next, list what is available and install one version. The README shows pyenv install -l for the supported list and pyenv install <version> to install, and notes that some non-silent installs pop up a wizard you click through, or you can pass -q for a quiet installation.

```bash
pyenv install -l
pyenv install 3.5.2
pyenv global 3.5.2
```

The version must be installed before it can be set. To pin a folder instead of the whole machine, run pyenv local from inside that folder. You can confirm which interpreter is actually running and where it lives.

```bash
python -c "import sys; print(sys.executable)"
```

The README shows the expected result as a path under .pyenv\pyenv-win\versions\<version>\python.exe. If that path points somewhere else, the shim chain is not in control.

## Where pyenv-win gets in the way

The rehash requirement is the sharpest edge. Install a package with a console entry point and the command will not resolve until you run pyenv rehash. Nothing in the shim layer detects the change for you.

The interpreter set is also bounded by a cached database. pyenv install -l reads a version list that is updated by pyenv update. A Python release newer than your cache will not appear until you refresh it. That is a deliberate design choice inherited from pyenv, and it means a fresh machine can lag behind the current release until someone runs the update command.

Windows itself adds friction. The README's note about disabling App Execution Aliases exists because the Store Python launcher competes for the same python name. On a managed corporate machine where you cannot change those aliases, or where PATH is locked by policy, pyenv-win may never take precedence. The manual settings section assumes you can edit system environment variables through the GUI.

Finally, pyenv-win manages interpreters, not packages. It does not create isolated dependency sets. If you need reproducible package resolution per project, you still need a virtual environment on top of the selected interpreter. pyenv-win decides which python runs; it does not decide what is installed.

## pyenv-win compared with uv and conda

uv and conda both overlap with pyenv-win, but the overlap is partial. conda ships its own Python builds and a package channel, so it controls the interpreter and the packages together. pyenv-win does not build interpreters or host a package index; it installs versions from its cached list and points PATH at them. If your team already standardizes on conda environments, adding pyenv-win creates two systems claiming authority over which python runs.

uv takes a different route again. It is a package and project manager that can also fetch interpreters as part of resolving a project. That means a single tool covers the job pyenv-win splits between version selection and whatever you use for dependencies. The trade-off is that uv's interpreter handling is tied to its project model, while pyenv-win's local version file is a plain marker that any editor or terminal respects once the shims are on PATH. For a repository that must work with several tools and no project manifest, the pyenv-win approach is less coupled.

A practical split: use pyenv-win when the interpreter choice must be global or per-folder and independent of any package manager, and use a project-scoped tool when reproducibility of the dependency set is the priority. The README positions the project as a single-purpose tool that does one thing well, and the comparison holds up only if you accept that boundary.

## Updating, licensing and the cost of keeping it current

pyenv-win ships under the MIT license, per the LICENSE file in the repository root and the badge in the README. MIT is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are retained. That is a general description of the license text, not legal advice, and anyone embedding the tool in a distributed product should read the LICENSE file themselves.

The update path is pyenv update for the version database and a re-run of the installer or a git pull for the tool itself, depending on which installation route you chose. The README does not document a rollback procedure for a failed upgrade, so a machine that breaks after an update has no documented way back short of reinstalling. That is worth knowing before you upgrade a shared build agent.

Maintenance signals are mixed. The last push to the repository was on 2026-09-18, and the repository is not archived. The most recent release listed is v3.1.1 from 2022-07-20, which means the tagged release history is far behind the commit history. If you depend on tagged releases for pinning, you are pinning to something several years old. The practical cost is that adopting pyenv-win means tracking the master branch or the installer script rather than a versioned artifact.

## Frequently asked questions about pyenv-win

The FAQ entries below cover the questions that come up most often when setting up pyenv-win. Answers are drawn from the README and repository files.

## Conclusion

Adopt pyenv-win if you work on Windows and need several Python interpreters side by side without activating a virtual environment for every switch. Skip it if you rely on the Windows Store Python launcher, since the README tells you to disable those aliases, or if you want a single tool that also resolves dependencies. Before committing, run pyenv install -l to confirm the interpreter you need appears in the cached list, then check that pyenv version reports the origin as the .python-version file after you set a local version.

## FAQ

### How do I uninstall pyenv-win?

The README does not document an uninstall procedure. The installation section lists PowerShell, Git commands, a zip, pip and Chocolatey as install routes, but no removal steps are given for any of them.

### Is pyenv-win better than uv?

They solve different problems. pyenv-win selects which Python interpreter runs on Windows and does not manage packages, while uv is a package and project manager that can also fetch interpreters. The choice depends on whether you need interpreter selection separate from dependency resolution.

### How do I use pyenv-win?

List available versions with pyenv install -l, install one with pyenv install <version>, then set it with pyenv global for the machine or pyenv local for the current folder. Run pyenv rehash after installing libraries so new executables get shims.

### How do I install pyenv-win?

The README supports PowerShell, Git commands, a pyenv-win zip, Python pip and Chocolatey. The PowerShell route downloads and runs install-pyenv-win.ps1, after which you reopen PowerShell and check pyenv --version.

### What is pyenv-win?

It is a Windows port of pyenv, forked from rbenv-win and modified for pyenv. It switches between multiple installed Python versions and follows the single-purpose tool model the README describes.

### How does pyenv-win compare with conda?

conda manages both the interpreter and packages through its own channel. pyenv-win only selects which Python version runs, so a project needing isolated dependencies still requires a virtual environment on top of the selected interpreter.

## Sources

- [License: MIT](https://github.com/pyenv-win/pyenv-win/blob/master/LICENSE)
- [Project website](https://pyenv-win.github.io/pyenv-win)
- [pyenv-win/pyenv-win on GitHub](https://github.com/pyenv-win/pyenv-win)
- [README](https://github.com/pyenv-win/pyenv-win/blob/master/README.md)
- [Releases](https://github.com/pyenv-win/pyenv-win/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pyenv-win-pyenv-win