Configuration

PVM uses three configuration mechanisms that compose together: a project-level file checked into your repository, a user-level file for personal preferences, and a Perl-standard dependency declaration. Most projects only need the first two.

pvm.toml

Project-level configuration. Place this file in your project root alongside cpanfile. It declares the project name and the Perl version the project requires, and can carry update settings for CI or team environments where you want a specific token or policy.

[project]
name = "my-app"
perl_version = "5.40.2"

[pvm.update]
github_token = ""
check_prerelease = false

The perl_version field is the version PVM will select when you run pvm use or when pvx resolves the interpreter for a script. If the version is not installed, PVM will tell you what to run to install it.

Commit pvm.toml to version control. It belongs alongside your code. Leave github_token empty here and set it in your user configuration or as an environment variable instead — tokens should not live in repositories.

User configuration

User-level preferences live at ~/.config/pvm/config.toml (following the XDG Base Directory spec). Settings here apply to all projects on your machine and are not checked into version control.

[pvm.update]
github_token = "ghp_..."
auto_update = true

This is the right place for your GitHub token. Setting auto_update = true means PVM will check for newer releases and update itself in the background. The token is used to raise GitHub API rate limits when PVM checks for new Perl releases or its own updates.

cpanfile

Perl's standard format for declaring module dependencies. PVM and pm read this file to know what to install. If you have an existing Perl project, you likely already have one.

requires 'DBI', '>= 1.643';
requires 'Mojolicious', '>= 9.0';

on 'test' => sub {
    requires 'Test::More', '>= 1.302';
};

on 'develop' => sub {
    requires 'Perl::Critic';
};

The top-level requires calls declare runtime dependencies. The on 'test' and on 'develop' blocks scope dependencies to specific phases. pm install installs runtime dependencies by default; pass --with-test or --with-develop to include the other phases.

cpanfile.snapshot

The lockfile. When you run pm sync, PVM reads your cpanfile, resolves the full dependency graph, and writes cpanfile.snapshot with exact version pins for every module in the tree. Subsequent installs read from the snapshot rather than resolving again, so every developer and every CI run gets the same versions.

pm sync                    # Install from snapshot, or generate if missing
pm sync --generate-only    # Generate snapshot without installing
pm sync --install-only     # Install from existing snapshot

Commit cpanfile.snapshot to version control alongside cpanfile. The snapshot is what makes builds reproducible. Update it deliberately with pm sync --generate-only when you want to pick up new versions, then review the diff before committing.

XDG Base Directory locations

PVM follows the XDG Base Directory Specification for all file placement. The defaults work on any standard Linux or macOS system. Override them by setting the corresponding environment variables.

Config
$XDG_CONFIG_HOME/pvm/ — defaults to ~/.config/pvm/. Holds config.toml.
Data
$XDG_DATA_HOME/pvm/ — defaults to ~/.local/share/pvm/. Holds installed Perl versions and named environments.
Cache
$XDG_CACHE_HOME/pvm/ — defaults to ~/.cache/pvm/. Holds downloaded archives and module caches. Safe to delete; PVM will repopulate on demand.

Environment variables

Environment variables take effect immediately without editing any file. They override file-based configuration and are useful in CI environments, containers, and one-off overrides.

PVM_PERL_VERSION
Override the active Perl version, regardless of what pvm.toml or .perl-version specifies.
GITHUB_TOKEN
GitHub token for release access. Raises API rate limits when PVM checks for Perl releases or its own updates. Equivalent to setting github_token in user configuration.
NO_COLOR
Disable all colored output. PVM respects the no-color.org convention: set this variable to any value to suppress color, regardless of terminal capabilities.
CLICOLOR_FORCE=1
Force colored output even when stdout is not a TTY. Useful when piping output to a pager or log collector that renders ANSI codes.
CLICOLOR=0
Disable colored output. An alternative to NO_COLOR for environments that use the CLICOLOR convention.

CPAN mirrors

pm fetches modules from CPAN mirrors. The default mirror list covers the major public mirrors, and pm will fall back to the next mirror if one is unavailable. You can set a preferred mirror explicitly — useful when you are behind a corporate proxy or want a geographically close mirror.

pm mirror https://cpan.metacpan.org    # Set mirror
pm mirror                              # Show current mirror

Default mirrors, tried in order:

The configured mirror is stored in user configuration and applies to all projects. Setting a mirror in one project does not override another project's mirror setting.