plenv

Show the currently selected Perl version and how it was selected

$ plenv version

$ plenv versions

$ plenv global [version]

$ plenv local [version]

$ plenv shell [version]

$ plenv

$ plenv help [command]

plenv command [arguments...]

install
    Installs a specific Perl version (requires the `perl-build` plugin).

versions
    Lists all Perl versions installed by `plenv`, indicating the currently active one.

global
    Sets the global default Perl version across all shell sessions.

local
    Sets the Perl version for the current directory and its subdirectories by creating a `.perl-version` file.

shell
    Sets the Perl version for the current shell session only. This setting takes precedence over local and global settings.

rehash
    Rebuilds the `plenv` shim executables. This command is essential after installing new Perl versions or any Perl modules via `cpan` or `cpanm`.

uninstall
    Uninstalls a specific Perl version from your `plenv` environment.

exec [args]
    Executes a command using the currently selected Perl environment, bypassing shims.

which
    Displays the full path to the executable that the `plenv` shim will invoke for the given command.

sh-init
    Prints the necessary shell initialization script for `plenv`. This output should be `eval`uated in your shell's startup file (e.g., `~/.bashrc`).

sh-update
    Updates the `plenv` installation itself to the latest version available in its Git repository.

plenv is a lightweight command-line tool designed to simplify the management of multiple Perl versions on a single system. Inspired by `rbenv`, it provides a convenient way for developers to switch between different Perl interpreters for various projects without conflicts. Instead of modifying the system's Perl installation, `plenv` works by inserting a directory of "shims" at the front of your PATH. When you run a command like `perl` or `cpan`, your shell finds the `plenv` shim first, which then delegates the command to the correct Perl version based on your project's configuration (via `.perl-version` files) or global settings. This approach ensures that different projects can use their specific Perl versions and associated modules, providing isolation and reproducibility for development environments. It's particularly useful for testing applications against multiple Perl releases or managing dependencies for various legacy and modern projects.

To enable `plenv` functionality, you must initialize it in your shell by adding `eval "$(plenv init -)"` to your shell's configuration file (e.g., `~/.bashrc` or `~/.zshrc`). After installing new Perl versions or Perl modules (e.g., with `cpan` or `cpanm`), you must run `plenv rehash` to update the shim executables; otherwise, newly installed commands or modules may not be found. `plenv` manages user-specific Perl installations and does not interfere with, or manage, the system's pre-installed Perl.

plenv operates by placing "shim" executables (small scripts) in `~/.plenv/shims` and ensuring this directory is at the front of your PATH environment variable. When you type a command like `perl` or `cpan`, your shell finds the `plenv` shim first. This shim then consults your `plenv` configuration (global, local, or shell settings) to determine which specific Perl version to use, and then transparently delegates the command to the actual Perl binary located in the corresponding `~/.plenv/versions//bin` directory. This transparent delegation means you don't need to manually manage your PATH for each Perl version you use.

While `plenv` provides the framework for managing Perl versions, the actual process of compiling and installing Perl from source code is handled by a separate, external plugin called `perl-build`. This plugin needs to be installed separately (typically by cloning its repository into `~/.plenv/plugins/`) for the `plenv install` command to function correctly. `perl-build` offers various options for customizing the Perl build process, such as configuring installation paths or enabling specific features.

plenv was developed as an open-source project, largely inspired by the successful `rbenv` tool for Ruby version management. It emerged to address the need for a similar lightweight, shim-based approach to managing multiple Perl installations, offering an alternative to more comprehensive and potentially heavier tools like `perlbrew`. Its development reflects a broader trend in developer tooling towards isolated, project-specific environments for language runtimes, making it easier to manage dependencies and test against various Perl versions.

perl(1), perlbrew(1), rbenv(1), pyenv(1)