Version Resolution

When you run a Perl command through PVM, it needs to decide which Perl version to use. PVM checks several sources in a fixed order, using the first one that produces a result.

Resolution order

PVM resolves the active Perl version using this precedence, from highest to lowest:

PVM_PERL_VERSION environment variable
.perl-version file in the current directory or any parent directory
Global version set via pvm global
System Perl (fallback)

The first source that specifies a version wins. If none of the first three are set, PVM falls back to whatever perl is on your PATH.

.perl-version files

Placing a .perl-version file in a directory pins the Perl version for that project. PVM searches upward from the current working directory, so you can put the file at the root of your project and it applies throughout the tree.

echo "5.40.2" > .perl-version

The file contains a single version string. PVM reads it the same way plenv does, so if you are migrating from plenv, your existing .perl-version files work without modification.

Setting versions

PVM provides three commands for controlling which version is active, each targeting a different scope:

pvm global 5.40.2       # Set default for all shells
pvm local 5.40.2        # Write .perl-version in current dir
pvm use 5.40.2          # Set for current shell session only
pvm global system       # Fall back to system Perl

pvm global: Writes the version to PVM's global configuration. This is the default used everywhere you haven't set a more specific version.
pvm local: Writes a .perl-version file in the current directory. Commit this file to version control to share the version requirement with your team.
pvm use: Sets PVM_PERL_VERSION in the current shell session. It does not persist across shells or terminals. Useful when you need to temporarily override the project version.
pvm global system: Removes the PVM global version setting, letting the system Perl serve as the default.

Checking the active version

To see which version PVM has resolved and why:

pvm current             # Show active version
pvm current --detailed  # Show version + resolution source
pvm current --path      # Show path to perl binary

pvm current --detailed is particularly useful when debugging unexpected version selections. It reports not just the version but which source in the resolution chain provided it — environment variable, .perl-version file, global config, or system fallback.

Shell integration

Shell integration enables automatic version switching when you change into a directory that contains a .perl-version file. Without it, you need to run pvm use manually.

Add the appropriate line to your shell profile:

# bash/zsh (~/.bashrc or ~/.zshrc)
eval "$(pvm init)"

# fish (~/.config/fish/config.fish)
pvm init | source

# PowerShell ($PROFILE)
pvm init | Invoke-Expression

After adding this and restarting your shell (or sourcing the profile), PVM will automatically activate the correct Perl version whenever you cd into a project directory.

Migrating from plenv or perlbrew

PVM is designed to be a drop-in replacement for plenv's version management. If you have existing .perl-version files, they work immediately — no changes needed.

To bring your existing Perl installations under PVM management:

pvm import-system       # Import system Perl
pvm versions            # See what's available

If you have Perl versions installed via plenv or perlbrew, install the same versions through PVM and your project configurations will continue to work. The .perl-version file format is shared across all three tools.