PHP version manager

Switch PHP versions like you change directories.

phpenv installs, pins, and switches PHP versions per project. Drop a .php-version in a folder and php becomes the right build the moment you cd in.

$ git clone https://github.com/phpenv/phpenv.git ~/.phpenv
Get started Read the docs

How it works

One shim layer, every version you need.

phpenv sits in front of php, php-fpm, pecl, and friends. It reads your project's version and routes each command to the matching build under ~/.phpenv/versions/.

Per-project versions

A .php-version file pins the interpreter for a directory and everything below it. No file, no surprise. Version selection is local to where you work.

Seamless shims

Lightweight shims on your PATH intercept every PHP executable and dispatch to the active build. Switching versions never touches the command you type.

Build any version php-build

Compile PHP 5.x through 8.x straight from source with a single phpenv install. Configure flags and PECL extensions per build through environment variables.

Plugin-extensible

Almost every step is a bash hook you can override. Drop plugins under plugins/ to add commands or reshape the build without patching phpenv itself.

Quick start

Up and running in five steps.

A plain git checkout, wired into your shell. Assumes ~/.profile; use your own init file (~/.bash_profile, ~/.zshrc) if that's where your shell reads config.

Homebrew shortcut

On macOS or Linux with Homebrew, this replaces steps 1 and 2. Then run steps 3 and 4 to enable phpenv.

brew install phpenv/tap/phpenv

Clone phpenv into your home directory

git clone https://github.com/phpenv/phpenv.git ~/.phpenv

Add the CLI to your PATH

echo 'export PATH="$HOME/.phpenv/bin:$PATH"' >> ~/.profile

Enable shims and autocompletion

echo 'eval "$(phpenv init -)"' >> ~/.profile

Restart your shell

exec $SHELL -l

Add php-build, then install a PHP

php-build is the phpenv plugin that compiles PHP from source.

git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build
phpenv install 8.3.13
phpenv global 8.3.13

Cheat sheet

The commands you'll actually use.

phpenv delegates to subcommands, git-style. Run phpenv help <command> for the full page on any of them.

phpenv install 8.3.13Build and install a PHP version from source (via php-build).
phpenv global 8.3.13Set the default version used across every shell.
phpenv local 7.4.33Pin a version for the current project by writing .php-version.
phpenv shell 8.2.0Override the version for just the current shell session.
phpenv versionsList every installed version and mark the active one.
phpenv versionShow the active version and what set it.
phpenv which phpPrint the real path a shim resolves to.
phpenv rehashRebuild shims after installing a new PHP binary.

Configuration

Environment variables.

Tune phpenv's behaviour without touching a config file.

PHPENV_VERSIONForce a specific version, above local and global.
PHPENV_ROOTWhere versions and shims live. Defaults to ~/.phpenv.
PHPENV_DEBUGEmit verbose debug output for troubleshooting.
PHPENV_HOOK_PATHExtra colon-separated paths searched for hooks.
PHPENV_DIRDirectory to start searching for .php-version. Defaults to $PWD.