pvm

Perl Version Manager. Installs, switches, and manages Perl versions. Handles workspaces, tools, environments, and shell integration.

pvm <command> [args...] [options]

For the exhaustive flag reference including internal commands, see pvm (full).

Version management

install [version]

Install a Perl version. Downloads a prebuilt binary by default; falls back to source build if no binary is available.
Key flags: --binary-only (skip source fallback), --source (force source build), --mirror <url> (alternate binary mirror), --jobs <n> (parallel build jobs).
Run pvm install --help for all options.

use [version]

Activate a Perl version in the current shell session. Requires shell integration (pvm init).

global [version]

Set the global default Perl version, used when no local or shell override applies. Pass system to fall back to the system Perl.
Flag: --unset (clear the global default).

local [version]

Pin a version for the current directory by writing a .perl-version file. PVM reads this file automatically on directory entry.
Flag: --unset (remove the pin).

versions

List installed Perl versions. Alias: list.
Flags: --paths (show install paths), --format <fmt> (output format).

available

List Perl versions available to install.
Flags: --include-dev (include development/RC releases), --format <fmt> (output format).

current

Show the currently active Perl version.
Flags: --bare (version string only), --detailed (show resolution chain), --json (JSON output), --path (show path to perl binary).

uninstall [version]

Remove an installed Perl version and its associated binaries.

rehash

Rebuild shims and update PATH for the current version. Run after installing new executables.

Build and import

build-perl [version|URL]

Build Perl from source. Accepts a version number or a direct URL to a source tarball. Leaves the result in the build directory for inspection before installing.

install-perl

Install Perl from a local build directory, archive file, or URL. Use after build-perl or to install a tarball you already have.

import-system

Import the system Perl into PVM so it appears in pvm versions and can be selected like any managed version.

download [version]

Download a Perl source tarball without building. Useful for air-gapped installs or pre-caching.

Project management

workspace init [name]

Initialize a new PVM-managed project in the current directory.
Flags: --template <name> (use a project template), --force (reinitialize an existing workspace).

workspace status

Show the current workspace: active version, installed modules, lock status.

workspace doctor

Check workspace health: missing modules, version mismatches, stale lockfile.
Flag: --fix (attempt to repair problems automatically).

test [pattern]

Run tests for the current workspace. Discovers tests automatically; optionally filter by glob pattern.
Flags: --verbose, --parallel (run tests in parallel), --coverage (emit coverage data).
Run pvm test --help for all options.

Module management

module

Unified module management. Wraps pm commands within the PVM context. See pm reference for subcommands.

Execution

run

Unified run command. Wraps pvx within the PVM context. See pvx reference for options.

Tool management

tool add [tool]

Install a named Perl tool into the PVM tool registry, making it available across all versions.

tool run

Run an installed tool.

tool list

List all installed tools.

tool upgrade

Upgrade an installed tool to its latest version.

Environment management

env list

List all named PVM environments.

env activate [name]

Activate a named environment. Requires shell integration.

env remove [name]

Delete a named environment and its installed modules.

Shell integration

init [shell]

Emit shell integration code. Pipe into your shell profile or evaluate directly.
Supported shells: bash, zsh, fish, powershell. Auto-detects if omitted.
Example: eval "$(pvm init)"

completion

Generate shell completion scripts for the detected or specified shell.

Self management

update

Update PVM itself to the latest release.

doctor

Diagnose PVM installation issues: missing shims, PATH problems, shell integration.
Flag: --fix (attempt to repair problems automatically).

version

Print the PVM version string.

Configuration

config

View and edit PVM configuration. See Configuration guide for available keys. Run pvm config --help for subcommands.