How to Install pyenv for ai-coding on mac linux and windows

The setup is straightforward on Mac and Linux. Most of the time goes into compiling Python from source. Windows uses a separate tool with pre-compiled binaries instead.

Machine learning frameworks are strict about Python versions. TensorFlow and PyTorch pin dependencies tightly. Even a minor mismatch can trigger errors unrelated to your code. If you run multiple projects with different requirements, one system Python becomes a problem.

Pyenv avoids that by giving each project its own interpreter. It stores versions in 

, separate from the system Python that macOS or Linux ships with. The shim layer intercepts each Python command. It routes that command to the active version for that directory. The operating system stays the same. Only the selected binary changes.

Before you start, leave your macOS system Python (

) alone. System Integrity Protection protects it, and pyenv shims never touch it. But any Python you installed through Homebrew or a standalone installer should go. Those installations sit ahead of pyenv shims in your PATH. They can intercept commands before pyenv runs.

Mac and Linux build interpreters from source, so they need compilation tools. Windows does not. Pyenv-win ships pre-compiled binaries and uses a separate codebase. It integrates with Windows environment variables and the registry. If you use Windows, the 

 is your reference, not the main pyenv docs.

On Apple Silicon Macs, Python 3.9 and above compile natively on ARM-64. Python 3.8 and below predate ARM-64 support and need Rosetta 2 to compile. If your course requires an older version, set up Rosetta first. That avoids troubleshooting during installation.

The problem usually shows up in a familiar way. A lab worked last week, and now 

 is broken. Most of the time, a background update or stray 

 changed your global Python environment. That can shift a version another package depends on.

Deep learning frameworks are especially fragile because they sit close to hardware. CUDA bindings, metal APIs, and accelerated compute libraries all depend on specific Python and library versions. One runtime may support a GPU library version that another cannot load. Reproducible results require locking the whole stack.

Why Version Pinning Matters for AI Lab Work

 file in your project directory. It is committed with your code. When you open that folder, pyenv reads the file and routes Python commands to the declared version. This happens automatically, with no manual switching. If a teammate clones your repo and has that version installed, they get the same interpreter.

PATH ordering makes this work. Pyenv’s shim directory must come before any other Python binary in your shell’s search path. If it does not, the shell uses the first interpreter it finds. That may not match what pyenv declared. The shell init hooks you add during setup handle this.

Because Mac and Linux build Python from source, your machine needs the right compiler tools before 

. Skip them, and the build fails partway through. Sometimes the error message is unclear.

. On Ubuntu or Debian Linux, the equivalents are 

 lists exact package names for each major Linux distribution. It is worth opening before your first install on a fresh machine.

You also need access to your shell configuration files. After installation, you add initialization lines to 

, depending on your shell and chip. If you have never edited one before, do a quick test first.

 before you start. Any binary listed above 

 will intercept Python calls before pyenv can. The system Python at 

 is protected and will not interfere. Do not touch it. A Python you installed through Homebrew or a standalone installer is different. Those need to come out, or pyenv’s shim layer will not function correctly.

Pyenv handles one job: choosing the active Python interpreter. It does not manage packages. That is by design.

The clean workflow uses three layers. Pyenv sets the interpreter version for a directory. A virtual environment, built with 

, sits on top of that interpreter. It holds the project’s dependencies. Your code runs inside the virtual environment. Nothing from one project leaks into another.

What catches students is this: you install a version with pyenv, then run 

 without activating a virtual environment. The packages land in the pyenv-managed interpreter itself. The next lab may use a different Python version, and those packages disappear. Activate a virtual environment for each project, every time.

Python 3.9 and above compile natively on Apple Silicon. If your course materials require Python 3.8 or older, install Rosetta 2 before running 

. Otherwise, the compiler stops with an error. When you can, use a version that compiles natively.

Pyenv is a pure shell script tool. It does not modify your system Python, and it does not need elevated privileges. It works through shims. These are small wrapper scripts at the front of your 

. They redirect each Python command to the right version for the current context.

 in your home directory, they run entirely in user space. The host operating system stays untouched.

How Pyenv Scopes Versions to Your Project

Pyenv checks three scopes in order: shell, local, and global.

) is session-only. It disappears when you close the terminal. The 

 file into the current directory. It activates whenever you are inside it, including subdirectories. The 

) acts as a fallback for directories without a 

For day-to-day AI lab work, local scope is the best choice. Enter a lab folder, and the correct interpreter activates automatically. Leave the folder, and it switches back.

There are three phases: install the tool, wire it into your shell, and install the Python version your project needs. Most people skip phase two. Then they wonder why 

On macOS, after your build dependencies are in place:

 through PowerShell. The README explains the exact steps, which differ from the Unix install.

 again. Confirm that nothing appears above 

After installation, pyenv does nothing useful until you add its init hooks to your shell profile. For zsh, add these lines to 

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

 to activate it. Without this step, your shims never load. Every 

Install the exact interpreter your TensorFlow or PyTorch lab requires:

For project-specific pinning, go to your lab directory and run:

 file at the project root. Each time you enter that directory, pyenv activates the correct version automatically. No manual switching between labs.

If your project requires Python 3.8 or older and you are on Apple Silicon, make sure Rosetta 2 is configured before running 

. Otherwise, the build fails during compilation.

Pyenv manages interpreters. It is not a package manager. The most common mistake is treating it like one.

The rule is simple: each project gets its own virtual environment. Build it on top of the pyenv-managed interpreter. Activate it before any 

 runs. Packages installed outside a virtual environment land in the interpreter itself. That creates the cross-project contamination pyenv is meant to prevent.

Which Python Installations to Remove — and Which to Leave

You will find conflicting advice on this. Both sides are partly right, but they are talking about different things.

 is protected by System Integrity Protection on macOS. It is isolated from pyenv entirely. Leave it alone.

The problem is user-managed Python installs. These include anything you installed through Homebrew or a standalone package. They may appear in your 

 and check the order of results. Any entry above 

 intercepts Python commands before pyenv sees them. Those are the installs to remove. The errors they cause, like wrong versions or missing packages, are hard to debug without understanding the PATH race.

The rule is simple: if you installed it yourself outside pyenv, and it appears above pyenv’s shims in your PATH, remove it.

 file to source control. It is small and unambiguous. It also ensures every teammate uses the same interpreter without discussion.

The most confusing post-install result is a setup that appears to do nothing. You set a version, run 

, and the shell still reports the system interpreter. Almost every case comes down to one of two things: the shell never loaded pyenv’s init block, or another Python binary won the PATH race.

Compilation errors usually mean the build environment is missing development headers. Verify that all packages listed in the prerequisites section are installed and linked correctly.

On Apple Silicon with Python 3.8 or older, the build halts if the system tries a native ARM-64 compile. Rosetta 2 must be active and configured first.

Depending on your terminal emulator, it may read different startup files. The zsh split between 

, while interactive non-login shells read 

. If your init block is in the wrong file for your terminal type, pyenv loads sometimes, but not always.

After editing the config file, reload it or restart the terminal. Changes do not apply to an already running session.

 is the first command to run when pyenv seems to route incorrectly. It lists every Python binary your shell can resolve, in PATH order. If the resolved path does not point into 

, another installation is intercepting the call. Identify it, remove it, and run the check again.

 returns the interpreter you declared in 

, version management is done. That file is also recognized by 

 and other modern Python tooling. The version pin travels with your project code instead of living only in your shell.

After a fresh pyenv install, check your course materials for the exact Python version they specify. Then run 

 with that number. Do not start with the latest version. After the right interpreter is in place, create a virtual environment scoped to that version and activate it before any 

That order matters. A virtual environment built on the wrong interpreter is just as broken as no virtual environment at all.

If a lab pins an older Python version, some PyTorch builds and CUDA-aligned packages cap out at Python 3.9 or 3.10. Run 

 against the requirements file before committing to a virtual environment. Dependency failures caught early are cheaper to fix than ones that appear mid-lab. Check the framework’s official compatibility matrix before running 

; those tables are the ground truth when course materials lag behind a release cycle.

Skip pyenv if your course provides Docker-based lab environments. When the Python version is built into the container image, adding a local version manager creates a redundant layer. Isolation is already handled at the container level.

Windows developers using pyenv-win should check the release notes if a specific runtime version is not immediately available. Updates can ship on a different schedule from the main project.

 is the primary reference for the tool and its wiki. The wiki lists exact build dependency package names for every major Linux distribution. Open it before your first 

Pin your Python versions from day one. The fewer unversioned assumptions in your setup, the more time you spend on the labs themselves.

AUTHOR

Dr. Dipen

The setup is straightforward on Mac and Linux. Most of the time goes into compiling Python from source. Windows uses a separate tool with pre-compiled binaries instead. Machine learning frameworks are strict about Python versions. TensorFlow and PyTorch pin dependencies tightly. Even a minor…

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Free Tools

How to Install pyenv for ai-coding on mac linux and windows

Tags

Responses (0)

Free AI Career Tools

AI Job Listings

ATS Resume Checker

Startup Perks

Masterclasses

Tutorials

Fullstack React with TypeScript