PVM Complete Reference

Every command, every flag, every option. See pvm for the concise version.

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

Version Management

install [version]

Install a Perl version. Accepts a version number, a partial version, or a URL. Downloads a binary release by default; falls back to building from source if no binary is available.

--source: Force a source build even when a binary is available.
--prefix <path>: Install to a custom prefix instead of the default PVM root.
--jobs <n>: Number of parallel make jobs during a source build. Default: number of CPUs.
--test: Run the Perl test suite after a source build.
--skip-build: Download only; do not build or install.
--binary-only: Fail if no binary release is available for the requested version.
--prefer-binary: Use a binary release when available; fall back to source otherwise. This is the default.
--force-source: Alias for --source.
--mirror <url>: Override the binary mirror URL for this installation.
--skip-cache: Re-download even if a cached download exists.
--skip-checksum: Skip SHA256 verification of the downloaded archive.
--no-patchperl: Skip applying patchperl fixes during a source build.

use [version[@library]]

Activate a Perl version in the current shell session. The optional @library suffix selects a local::lib library directory. Outputs shell code; must be evaluated via eval "$(pvm use ...)" or the shell integration.

global [version]

Set the global default Perl version, written to ~/.pvm/version. Accepts a version string or the special value system to defer to the system Perl. With no argument, prints the current global version.

--unset: Remove the global version setting, reverting to system Perl.

local [version]

Set the local Perl version for the current directory, written to .perl-version. With no argument, prints the current local version.

--unset: Remove the .perl-version file.

versions (alias: list)

List all installed Perl versions. Marks the active version.

--paths: Show the installation path for each version.
--source: Show how each version was installed (binary or source).
--format <text|json>: Output format. Default: text.

available

List Perl versions available to install from the configured mirrors.

--include-dev: Include development and release-candidate versions.
--format <text|json|plain>: Output format. Default: text.

current

Show the active Perl version.

--bare: Print the version string only, no labels.
--detailed: Include source, path, and configuration summary.
--json: Output as JSON.
--path: Print the path to the perl binary.
--validate: Exit non-zero if the active version is not installed.

uninstall [version]

Remove an installed Perl version and its entire directory tree.

resolve [version]

Resolve a version string (partial, alias, or range) to the best matching installed version and print it. Useful for scripting.

detect-version

Walk up the directory tree from the current directory looking for a .perl-version file and print the version it contains.

download [version]

Download the source archive for a Perl version without building or installing it.

rehash

Regenerate the shims in ~/.pvm/shims so newly installed executables are visible on PATH.

--dry-run: Show what would be done without making changes.
--verbose: Print each shim as it is created or removed.

Build & Import

build-perl [version|URL]

Build Perl from source. Accepts a version number or a direct URL to a source tarball.

--jobs <n>: Number of parallel make jobs. Default: number of CPUs.
--prefix <path>: Installation prefix for the build output.
--configure-args <args>: Extra arguments to pass to Configure.

install-perl

Install Perl from a pre-built archive, a local directory, or a URL. Intended for use after build-perl or when integrating externally built binaries.

import-system

--force: Re-import even if the system Perl is already registered.

Project Management

workspace init [name]

Initialize a PVM-managed project in the current directory. Creates pvm.toml and optionally a starter layout.

--template <name>: Use a named project template. See workspace templates for available names.
--force: Overwrite an existing pvm.toml.

workspace status

Show the status of the current workspace: active Perl version, installed modules, and any pending changes relative to the lockfile.

workspace doctor

Check the workspace for configuration problems, missing dependencies, and version mismatches.

--fix: Automatically resolve detected problems where possible.

workspace templates

List available project templates and their descriptions.

workspace validate

Validate pvm.toml against the schema and report any errors.

test [pattern]

Run tests for the current project. Discovers test files automatically; accepts an optional glob pattern to filter.

--verbose: Print each test as it runs.
--parallel: Run tests in parallel.
--coverage: Collect code coverage data using Devel::Cover.
--perl <version>: Run tests under a specific Perl version.
--test-dir <path>: Look for tests in a specific directory instead of the default t/.

Module Management

module: Unified module management. Delegates to pm. Accepts all pm subcommands and flags. See pm reference.

Execution

run: Unified script and tool execution. Delegates to pvx. Accepts all pvx options and flags. See pvx reference.

Tool Management

tool add [tool[@version]]: Install a Perl tool (a CPAN distribution that provides executables) into the PVM tools directory, isolated from project dependencies.
tool run: Run a managed tool without adding it to the active environment's PATH.
tool list: List installed tools and their versions.
tool upgrade: Upgrade all installed tools to their latest available versions.
tool uninstall: Remove a managed tool.
tool shim install: Install shell integration for tool shims, adding the shims directory to PATH.
tool shim remove: Remove tool shim shell integration.
tool shim list: List installed tool shims.
tool shim status: Show whether shim integration is active and which tools have shims.
tool lsp: LSP server integration for tools. Not yet available.

Environment Management

env list: List named persistent execution environments and their active Perl version.
env activate [name]: Activate a named environment in the current shell. Outputs shell code; must be evaluated.
env remove [name]: Delete a named environment and its module directory.
env info [name]: Show details about a named environment: Perl version, path, installed modules.

Shell Integration

init [shell]: Emit shell initialization code. When shell is omitted, auto-detects the current shell. Add eval "$(pvm init)" to your shell profile. Supports bash, zsh, fish, and pwsh.
shell setup: Interactive shell setup wizard. Detects the current shell, edits the profile file, and verifies the integration.
completion: Generate shell completion scripts for the current or specified shell. Pipe to a file and source it, or follow the printed instructions.

Self Management

self

Self-management command group. Subcommands manage the PVM binary itself.

update

Update the PVM binary to the latest release.

--dry-run: Check for an update and report what would happen without downloading or replacing.
--no-backup: Do not keep a backup of the previous binary.
--no-rollback: Do not restore the previous binary if the update fails.
--prerelease: Allow updating to pre-release versions.
--token <token>: GitHub personal access token for accessing private or rate-limited releases.
--ignore-install-method: Update even when PVM was installed by a package manager or other external method.

auto-update [enable|disable|config|check|status]

Manage automatic background update checks.

enable: Enable automatic update checks.
disable: Disable automatic update checks.
config: Show or edit auto-update configuration (interval, channel, token).
check: Run an update check immediately without waiting for the next scheduled check.
status: Show whether auto-update is enabled, the last check time, and any pending update.

version

Print the PVM version string and exit.

doctor

Diagnose common PVM installation and configuration issues.

--fix: Attempt to automatically resolve detected issues.

changelog

Display the full PVM changelog.

release-notes [version]

Display release notes for a specific version. Defaults to the current version.

shims-dir

Print the path to the PVM shims directory. Useful for configuring PATH manually.

upload-binary [directory]

Upload built binaries to the release mirror. Maintainer command; requires appropriate credentials.

Configuration

config: Read, write, and manage PVM configuration. Without a subcommand, prints the active configuration. Subcommands: get <key>, set <key> <value>, unset <key>, list, edit (open in $EDITOR).

Internal Commands

These commands are invoked by shell integration and are not intended for direct use.

sh-use [version[@library]] (internal): Generate the shell code needed to activate a Perl version and optional local::lib library in the current shell session. Called by the pvm use shell function created by pvm init.
sh-env-activate [name] (internal): Generate the shell code needed to activate a named environment. Called by the pvm env activate shell function.
show-alerts (internal): Check whether there are pending alerts or notices to display in the user's terminal (e.g. available updates, deprecation warnings). Called during shell initialization. Exits zero silently when there is nothing to show.

Help System

help [command]: Print help for any command. With no argument, prints a summary of all top-level commands.
help workflows: Print descriptions of common multi-step workflows with example command sequences.
help getting-started: Print the new-user guide: installation, first version, first project.
help troubleshooting: Print troubleshooting guidance for common problems.
help next: Print suggested next steps based on the current project state.
help types: Print documentation for the PVM type system and PSC type inference.