Isolation Levels

PVX controls how much of your installed module environment a script can see. Three isolation levels cover the common cases, and named environments handle anything that needs to persist across runs.

Global

The default. Scripts run against your full installed module set and inherit the current environment. This is the right choice for everyday development: no overhead, no surprises, your modules are available.

pvx script.pl
pvx --isolation global script.pl

If you have DBI, Mojolicious, and a dozen other modules installed, a script run under global isolation can use all of them without any extra flags.

Local

Creates a temporary local::lib directory before execution and installs any required modules into it. Your global module installation is visible but not written to. When the script finishes, the temporary directory is removed.

pvx --isolation local script.pl

This is useful in CI pipelines or when you want to test module installation without touching your development environment. If you need to inspect what was installed, pass --no-cleanup to keep the directory after execution:

pvx --isolation local --no-cleanup script.pl

Clean

Starts with no pre-existing modules — only Perl's core modules are available. Any modules your script needs must be declared explicitly with --require. If you forget a dependency, the script fails rather than silently falling back to something you happen to have installed.

pvx --isolation clean --require DBI script.pl

Use this when you want to verify that your dependency declarations are complete. A script that passes under clean isolation will work anywhere the listed modules can be installed. A script that passes under global isolation might have undeclared dependencies that only exist on your machine.

Named Environments

All three isolation levels are ephemeral by default: the environment is set up for a single run, then discarded. Named environments change that. A named environment is created once, persists on disk, and is reused on subsequent runs.

pvx --name myproject --require DBI --require Mojolicious script.pl

The first invocation creates the environment and installs the declared modules. Later invocations reuse it, skipping the installation step. This makes named environments fast after the first run, which matters for scripts you call frequently.

Manage named environments with pvm env:

pvm env list               # List all environments
pvm env activate myproject # Activate in current shell
pvm env info myproject     # Show environment details
pvm env remove myproject   # Delete environment

Activating an environment in your current shell sets PERL5LIB so that interactive use and editor tooling pick up the same modules your scripts see.

Environment Variable Control

Isolation controls which modules are visible. Environment variable control is a separate concern: which variables from your current shell are passed into the script.

Use --preserve-env to allow specific variables through, and --clear-env to strip variables you want the script not to see:

pvx --preserve-env HOME --preserve-env USER script.pl
pvx --clear-env DATABASE_URL script.pl

These flags compose with any isolation level. A clean environment combined with explicit variable allowlisting gives the most reproducible execution context.

Choosing a Level

Global: Day-to-day development, running tests, quick scripts. Use this unless you have a specific reason not to.
Local: Testing module installation behavior, CI/CD pipelines where you want a clean install on each run without affecting the global environment.
Clean: Verifying that dependency declarations are complete. Reproducibility testing. Checking that a script will work for someone who doesn't have your full module stack installed.
Named: Project-specific environments you return to regularly. Shared team configurations where everyone needs the same module set. Anywhere you want isolation without paying the installation cost on every run.