Getting Started with PVM

PVM is a fast, cross-platform Perl development toolkit. This guide walks you through installation, shell integration, and creating your first project. By the end you will have a working Perl environment managed entirely by PVM.

Install PVM

The install script detects your platform, downloads the latest release, and places the binary in ~/.local/bin.

curl -fsSL https://pvm.tools/install.sh | sh

Set PVM_INSTALL_DIR to install somewhere else:

PVM_INSTALL_DIR=/usr/local/bin curl -fsSL https://pvm.tools/install.sh | sh

Build from source (Go 1.24+)

git clone https://github.com/perigrin/pvm.git && cd pvm && make

Verify the installation

Once the binary is on your path, confirm it is working:

pvm version

Set up shell integration

Shell integration lets PVM automatically switch Perl versions when you enter a project directory. Add the appropriate line to your shell's startup file.

bash / zsh

eval "$(pvm init)"

fish

pvm init | source

PowerShell

pvm init | Invoke-Expression

Open a new terminal session (or reload your shell config) after adding the line. Shell integration is what makes .perl-version files effective — PVM reads the file and switches to the right Perl version automatically.

Install a Perl version

Check which versions are available, then install the one you want.

pvm available          # List versions you can install
pvm install 5.40.2     # Install a specific version

PVM downloads a prebuilt binary when one is available for your platform, falling back to a source build if needed. After installation, switch to the new version:

pvm use 5.40.2

Create your first project

PVM organizes work around projects. A project is any directory that contains a .perl-version, cpanfile, or pvm.toml file. Use the workspace command to set one up:

pvm workspace init my-app
cd my-app

This creates a pvm.toml and a .perl-version file pinned to your current Perl version.

Add and install dependencies

PVM ships with pm, a module manager that tracks your dependencies in a cpanfile and locks them in a cpanfile.snapshot.

pm add DBI                   # Add a runtime dependency
pm add Test::More --dev      # Add a development dependency
pm install                   # Install everything in the cpanfile

The --dev flag marks a module as a development-only dependency — it will not be included when you package your project for distribution.

Key concepts

Project context

PVM detects which project you are in by looking for .perl-version, cpanfile, or pvm.toml in the current directory and its parents. When shell integration is active, the Perl version switches automatically as you move between projects.

Module management

The pm command handles everything related to CPAN modules: adding dependencies, installing them, syncing lockfiles, and searching the registry. Run pm --help for the full list of subcommands.

Version resolution

PVM resolves which Perl to use in this order: the PERL_VERSION environment variable, then .perl-version in the current or nearest parent directory, then the global default set with pvm use. See Version Resolution for the full rules.