Every Linux PHP developer knows the dance. You need to switch from PHP 8.1 to 8.3. You run your sudo commands, update your global symlinks, and then realize your local development server in the other window just crashed because it was running on the old version.

Why should managing PHP versions be a system-wide struggle?

The Solution: Per-Shell Version Isolation

phpvm brings the seamless developer experience of tools like pyenv, rbenv, or nvm to the PHP ecosystem on Linux.

Instead of changing /usr/bin/php globally, it uses a lightweight shim directory prepended to your PATH. When you call php, the shim inspects your environment variables and forwards the execution to the correct binary.

It supports three layers of resolution, falling back gracefully:

1. Shell pin: Pinned manually via phpvm shell <version>
2. Project default: Resolved from .php-version or composer.json requirements when you cd into a directory
3. Global default: The system fallback managed by update-alternatives

Effortless Provisioning

No need to look up repository installation guides. The built-in installer automatically detects your distribution (Ubuntu or Debian) and configures the appropriate upstream repositories (Ond?ej Sur�'s PPA or deb.sury.org) to fetch the exact CLI and FPM packages you need.

Polish in v2.5.1

Our latest release focuses on making the environment rock-solid:

• Tray App Auto-Start: Spawns the GTK desktop tray app immediately after installation by resolving the graphical session environment from active processes.
• PATH Priority: Actively prevents IDEs, login shells, or snap profiles from overriding the shim's position in PATH.
• Clean Cleanup: Ensures all background processes are terminated during uninstallation.

Getting Started

You can install or upgrade using the interactive script:

curl -fsSL https://raw.githubusercontent.com/rijverse/phpvm/main/install.sh | sudo bash

If you are already running v2.5.0, simply run:

phpvm --self-update

Check out the project website, or find the full documentation, TUI recipes, and GTK setup instructions on GitHub:

Website: rijverse.github.io/phpvm

GitHub: github.com/rijverse/phpvm