PERLBREW(1p)

📦
version 1.02 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 PERLBREW(1p) — User Contributed Perl Documentation 💖

okay bestie, welcome to the perlbrew(1p) page from the User Contributed Perl Documentation. this is literally your Perl environment manager, and she's iconic. no cap.

🌸 NAME 🌸

perlbrew — Perl environment manager. periodt.

✨ SYNOPSIS ✨

the command syntax is giving:

perlbrew <command> [options] [arguments]

Commands:

  • init — initializes the perlbrew environment. 💅
  • info — shows useful information about the perlbrew installation.
  • install — installs perl.
  • uninstall — uninstalls the given installation.
  • available — lists perls available to install.
  • lib — manages local::lib directories.
  • alias — gives perl installations a new name.
  • upgrade-perl — upgrades the current perl.
  • list — lists perl installations.
  • use — uses the specified perl in current shell.
  • off — turns off perlbrew in current shell.
  • switch — permanently uses the specified perl as default.
  • switch-off — permanently turns off perlbrew (reverts to system perl).
  • exec — executes programs with specified perl environments.
  • list-modules — lists installed CPAN modules for the current Perl version in use.
  • clone-modules — re-installs all CPAN modules from one installation to another.
  • self-install — installs perlbrew itself under PERLBREW_ROOT/bin.
  • self-upgrade — upgrades perlbrew itself.
  • install-patchperl — installs patchperl.
  • install-cpanm — installs cpanm, a friendly companion.
  • install-cpm — installs cpm, a faster but still friendly companion.
  • install-multiple — installs multiple versions and flavors of perl.
  • download — downloads the specified perl distribution tarball.
  • clean — purges tarballs and build directories.
  • version — displays version.
  • help — reads more detailed instructions.

Generic command options:

  • -q, --quiet — be quiet on informative output message.
  • -v, --verbose — tell me more about it.

See perlbrew help for the full documentation of perlbrew, or

See perlbrew help <command> for detail description of the command.

🎀 CONFIGURATION 🎀

PERLBREW_ROOT

By default, perlbrew builds and installs perls into $ENV{HOME}/perl5/perlbrew directory. To use a different directory, set this environment variable in your bashrc to the directory in your shell RC before sourcing perlbrew's RC. it's giving setup energy.

It is possible to share one perlbrew root with multiple user account on the same machine. Therefore people do not have to install the same version of perl over and over. Let's say /opt/perl5 is the directory we want to share. All users should be able append this snippet to their bashrc to make it effective:

export PERLBREW_ROOT=/opt/perl5
source ${PERLBREW_ROOT}/etc/bashrc

After doing so, everyone's PATH should include /opt/perl5/bin and /opt/perl5/perls/${PERLBREW_PERL}/bin. Each user can invoke perlbrew switch and perlbrew use to independently switch to different perl environment of their choice. However, only the user with write permission to $PERLBREW_ROOT may install CPAN modules. This is both good and bad depending on the working convention of your team. team vibe check, honestly.

If you wish to install CPAN modules only for yourself, you should use the lib command to construct a personal local::lib environment. local::lib environments are personal, and are not shared between different users. For more detail, read perlbrew help lib and the documentation of local::lib.

If you want even a cooler module isolation and wish to install CPAN modules used for just one project, you should use carton for this purpose. project isolation? we love to see it.

It is also possible to set this variable before installing perlbrew to make perlbrew install itself under the given PERLBREW_ROOT:

export PERLBREW_ROOT=/opt/perl5
curl -L https://install.perlbrew.pl | bash

After doing this, the perlbrew executable is installed as /opt/perl5/bin/perlbrew.

PERLBREW_HOME

By default, perlbrew stores per-user setting to $ENV{HOME}/.perlbrew directory. To use a different directory, set this environment variable in your shell RC before sourcing perlbrew's RC.

In some cases, say, your home directory is on NFS and shared across multiple machines, you may wish to have several different perlbrew setting per-machine. To do so, you can use the PERLBREW_HOME environment variable to tell perlbrew where to look for the initialization file. Here's a brief bash snippet for the given scenario.

if [ "$(hostname)" == "machine-a" ]; then
    export PERLBREW_HOME=~/.perlbrew-a
elif [ "$(hostname)" == "machine-b" ]; then
    export PERLBREW_HOME=~/.perlbrew-b
fi

source ~/perl5/perlbrew/etc/bashrc

PERLBREW_CONFIGURE_FLAGS

This environment variable specify the list of command like flags to pass through to 'sh Configure'. By default it is '-de'.

PERLBREW_CPAN_MIRROR

The CPAN mirror url of your choice. By default, https://cpan.metacpan.org is used. mirror mirror on the wall, who's the freshest CPAN of them all? 💅

🚀 COMMAND: INIT 🚀

Usage: perlbrew init

The init command should be manually invoked whenever you (the perlbrew user) upgrade or reinstall perlbrew.

If the upgrade is done with self-upgrade command, or by running the one-line installer manually, this command is invoked automatically. auto-magic, slay.

🔍 COMMAND: INFO 🔍

info [module]

Usage: perlbrew info [ <module> ]

Display useful information about the perlbrew installation.

If a module is given the version and location of the module is displayed.

📦 COMMAND: INSTALL 📦

Usage:

perlbrew install [options] <perl-release>
perlbrew install [options] /path/to/perl-5.14.0.tar.gz
perlbrew install [options] /path/to/perl/git/checkout/dir
perlbrew install [options] https://example.com/mirror/perl-5.12.3.tar.gz

Build and install the wanted perl. The last argument can be a short string designating a specific version which can be known from the output of perlbrew available, a path to a pre-downloaded tarball, a path to a git-checkout of perl5 repo, or a URL to a tarball. so many ways to serve perl, obsessed.

The format of <perl-release> looks like:

perl-<version>
perl-stable
perl-blead
<version>
stable
blead

Version numbers usually look like 5.x.xx, or perl-5.xx.x-RCx for release candidates.

Version stable is a special token that means whatever the latest stable version is at the moment.

Version blead is also a special token that means whatever the latest version in the repository, which is downloaded from this specific URL regardless of mirror settings:

https://github.com/Perl/perl5/archive/blead.tar.gz

The specified perl is downloaded from the official CPAN website or from the mirror site configured before.

Version number alone without the perl- prefix means the official release provided by perl5 porters.

Options for install command:

  • -f, --force — force installation.
  • -j $n — parallel building and testing. ex. perlbrew install -j 5 perl-5.14.2
  • -n, --notest — skip testing.
  • --switch — automatically switch to this Perl once successfully installed, as if with perlbrew switch <version>.
  • --as — install the given version of perl by a name. ex. perlbrew install perl-5.6.2 --as legacy-perl
  • --noman — skip installation of manpages.
  • --thread — build perl with usethreads enabled.
  • --multi — build perl with usemultiplicity enabled.
  • --64int — build perl with use64bitint enabled.
  • --64all — build perl with use64bitall enabled.
  • --ld — build perl with uselongdouble enabled.
  • --debug — build perl with DEBUGGING enabled.
  • --clang — build perl using the clang compiler.
  • --no-patchperl — skip calling patchperl.
  • -D, -U, -A — switches passed to perl Configure script. ex. perlbrew install perl-5.10.1 -D usemymalloc -U versiononly
  • --destdir $path — install perl as per 'make install DESTDIR=$path'.
  • --sitecustomize $filename — specify a file to be installed as sitecustomize.pl.
  • --mirror $URL — specify a CPAN-mirror URL. The default value of this is https://www.cpan.org.

By default, all installations are configured after their name like this:

sh Configure -de -Dprefix=$PERLBREW_ROOT/perls/<name>

🧬 COMMAND: INSTALL-MULTIPLE 🧬

Usage: perlbrew install-multiple [options] <perl-version-1> <perl-version-2> ...

Build and install the given versions of perl.

install-multiple accepts the same set of options as the command install plus the following ones:

  • --both $flavor — where $flavor is one of thread, multi, ld, 64int, 64all, debug and clang. For every given perl version, install two flavors, one with the flag --$flavor set and the other with out. --both can be passed multiple times with different values and in that case, all the possible combinations are generated.
  • --common-variations — equivalent to --both thread --both ld --both 64int.
  • --all-variations — generates all the possible flavor combinations.
  • --append $string — appends the given string to the generated names.

For instance:

perlbrew install-multiple 5.18.0 blead --both thread --both debug

Installs the following perls:

perl-blead
perl-blead-debug
perl-blead-thread-multi
perl-blead-thread-multi-debug
perl-5.18.0
perl-5.18.0-debug
perl-5.18.0-thread-multi
perl-5.18.0-thread-multi-debug

(note that the multi flavor is selected automatically because thread requires it)

Another example using custom compilation flags:

perlbrew install-multiple 5.18.0 --both thread -Doptimize='-O3' --append='-O3'

🗑️ COMMAND: UNINSTALL 🗑️

Usage:

perlbrew uninstall <name>

Alternatively:

perlbrew delete <name>
perlbrew rm <name>

Uninstalls the given perl installation. The name is the installation name as in the output of perlbrew list. This effectively deletes the specified perl installation, and all libs associated with it. gone, bye, no refunds bestie.

🪄 COMMAND: USE 🪄

Usage: perlbrew use [perl-<version> | <version> | <name>]

Use the given version perl in current shell. This will not effect newly opened shells.

Without a parameter, shows the version of perl currently in use. current shell main character energy ✨

💅 COMMAND: SWITCH 💅

Usage:

perlbrew switch [ <name> ]

Okay so this one is the glow-up command bestie. You give it a version and it switches to that version AND makes it the default for this terminal session and every future one. Like, permanently your main character now. 👑

If you pass no parameter at all? It just tells you which perl is currently selected. A little vibe check, if you will. ✨

📋 COMMAND: LIST 📋

Usage:

perlbrew list

Lists every single perl installation chilling inside the perlbrew root, which is specified by the $PERLBREW_ROOT environment variable. By default, that value is ~/perl5/perlbrew. 🏠

If some perl installations have libs attached to them, those libs get included as part of the name. And here's the slay part: the output items in this list? They can be used as the argument in a bunch of other commands. So this list is basically your menu of valid arguments. 🍓

🌈 COMMAND: AVAILABLE 🌈

Usage:

perlbrew available [--all]

Lists the recently available versions of perl on CPAN. So you can see what's out there before you commit. 👀

By default, it lists the latest sub-version of each stable version. Just the stable baddies.

To get a list of all perls ever released — including development and RC versions — run the command with the --all option. That's the deep lore dive. 🕳️

🙈 COMMAND: OFF 🙈

Usage:

perlbrew off

Temporarily disables perlbrew in the current shell. Effectively re-enables the default system Perl, whatever that is. So your shell goes back to the plain system one. 🫶

Heads up bestie: this command only works if you add the statement source $PERLBREW_ROOT/etc/bashrc in your shell initialization (bashrc / zshrc). No init line, no off switch. 😭

💀 COMMAND: SWITCH-OFF 💀

Usage:

perlbrew switch-off

Permanently disables perlbrew. (Original says "Permananently", and honestly, same energy.) Use the switch command to re-enable it. Or invoke the use command to enable it only in the current shell. 🔁

Also re-enables the default system Perl, whatever that is. System perl really said "I never left". 💅

🎀 COMMAND: ALIAS 🎀

Usage:

perlbrew alias [-f] create <name> <alias>

Create an alias for the installation named <name>.

Usage:

perlbrew alias [-f] rename <old_alias> <new_alias>

Rename the alias to a new name.

Usage:

perlbrew alias delete <alias>

Delete the given alias.

Nicknames for your perls!! It's giving "saving your contacts as emojis". 📱✨

🔥 COMMAND: EXEC 🔥

Usage:

perlbrew exec [options] <command> <args...>

Options for the exec command:

  • --with perl-version,... — only use these versions
  • --min n.nnnnn — minimum perl version (format is the same as in use 5.012)
  • --max n.nnnnn — maximum perl version
  • --halt-on-error — stop on first nonzero exit status

Executes a command for each perl installation, one by one. Like a little parade of perls marching through your command. 🚶‍♀️🚶‍♀️🚶‍♀️

For example, run a Hello program:

perlbrew exec perl -e 'print "Hello from $]\n"'

The output looks like this:

perl-5.12.2
==========
Hello word from perl-5.012002

perl-5.13.10
==========
Hello word from perl-5.013010

perl-5.14.0
==========
Hello word from perl-5.014000

Notice that the command is not executed in parallel. One at a time, patient queen. 🧘‍♀️

When the --with argument is provided, the command will be only executed with the specified perl installations. The following command installs the Moose module into perl-5.12, regardless of the current perl:

perlbrew exec --with perl-5.12 cpanm Moose

Multiple installation names can be provided:

perlbrew exec --with perl-5.12,perl-5.12-debug,perl-5.14.2 cpanm Moo

They are split by either spaces or commas. When spaces are used, it is required to quote the whole specification as one argument — but then, commas can be used in the installation names:

perlbrew exec --with '5.12 5.12,debug 5.14.2@nobita @shizuka' cpanm Moo

As demonstrated above, the perl- prefix can be omitted, and lib names can be specified too. Lib names can appear without a perl installation name — in such cases it is assumed to be "current perl". 🦋

At the moment, any specified names that fail to be resolved as real installation names are silently ignored in the output. Also, the command exit statuses are not populated back. So no receipts, sadly. 😶

🧚 COMMAND: ENV 🧚

Usage:

perlbrew env [ <name> ]

Low-level command, bestie — this is the backstage pass. 🎫 Invoke this command to see the list of environment variables that are set by perlbrew itself for shell integration.

The output is something similar to this (if your shell is bash/zsh):

export PERLBREW_ROOT=/Users/gugod/perl5/perlbrew
export PERLBREW_VERSION=0.31
export PERLBREW_PATH=/Users/gugod/perl5/perlbrew/bin:/Users/gugod/perl5/perlbrew/perls/current/bin
export PERLBREW_PERL=perl-5.14.1

tcsh / csh users should see setenv statements instead of export. Different shell, different dialect. 🐚

Usage:

perlbrew symlink-executables [ <name> ]

Low-level command. This one is used to create the perl executable symbolic link to, say, perl5.13.6. This is only required for development versions of perls. 🛠️

You don't need to do this unless you have been using old perlbrew to install perls, and you find yourself confused because the perl that you just installed appears to be missing after invoking use or switch. perlbrew changed its installation layout since version 0.11, which generates symlinks to executables in a better way. So this is very much a legacy-repair situation. 🧹

If you just upgraded perlbrew (from 0.11 or earlier versions) and perlbrew switch failed to work after you switch to a development release of perl, say, perl-5.13.6, run this command:

perlbrew symlink-executables perl-5.13.6

This essentially creates this symlink:

${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl
-> ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl5.13.6

Newly installed perls, whether they are development versions or not, do not need manual treatment with this command. Fresh installs are already iconic. ✨

🍓 COMMAND: INSTALL-CPANM 🍓

Usage:

perlbrew install-cpanm

Installs the cpanm standalone executable in $PERLBREW_ROOT/bin. 🎁

For more rationale about the existence of this command, read <https://perlbrew.pl/Perlbrew-and-Friends.html>

Usage:

perlbrew install-cpm

Installs the cpm standalone executable in $PERLBREW_ROOT/bin.

Two for the price of one heading, we love to see it. 💖

🌸 COMMAND: INSTALL-PATCHPERL 🌸

Usage:

perlbrew install-patchperl

Installs the patchperl standalone executable in $PERLBREW_ROOT/bin. This is automatically invoked if your perlbrew installation is done with the installer, but not with cpan. So don't panic if it's already there. 🙈

For more rationale about the existence of this command, read <https://perlbrew.pl/Perlbrew-and-Friends.html>

👑 COMMAND: SELF-UPGRADE 👑

Usage:

perlbrew self-upgrade

This command upgrades Perlbrew to its latest version. Glow up, but for your tooling. 💅✨

⭐ COMMAND: SELF-INSTALL ⭐

Usage:

perlbrew self-install
NOTICE: You should not need to run this command in your daily routine. Like, genuinely, this is not a casual Tuesday thing.

This command installs perlbrew itself to $PERLBREW_ROOT/bin. It is intended to be used by the perlbrew installer. However, you could manually do the following to re-install only the perlbrew executable:

curl https://raw.githubusercontent.com/gugod/App-perlbrew/master/perlbrew -o perlbrew
perl ./perlbrew self-install

It is slightly different from running the perlbrew installer because patchperl is not installed in this case. So it's the diet version of the install. 🥤

🧼 COMMAND: CLEAN 🧼

Usage:

perlbrew clean

Removes all previously downloaded Perl tarballs and build directories. Spring cleaning for your perlbrew root, no cap. 🧽🌸

🔖 COMMAND: VERSION 🔖

Usage:

perlbrew version

Shows the version of perlbrew. Short, sweet, iconic. 💫

🦋 COMMAND: LIB 🦋

Usage:

perlbrew lib <action> <lib-name>
perlbrew lib list
perlbrew lib create <lib-name>
perlbrew lib delete <lib-name>

The lib command is used to manipulate local::lib roots inside perl installations. Effectively it is similar to perl -Mlocal::lib=/path/to/lib-name, but a little bit more than just that. Overachiever behaviour. 💅

A lib name can be a short name, containing alphanumeric characters, like 'awesome', or a full name, prefixed by a perl installation name and a '@' sign — for example, 'perl-5.14.2@awesome'.

Here are some brief examples to invoke the lib command:

# Create lib perl-5.12.3@shizuka
perlbrew lib create perl-5.12.3@shizuka

# Create lib perl-5.14.2@nobita and perl-5.14.2@shizuka
perlbrew use perl-5.14.2
perlbrew lib create nobita
perlbrew lib create shizuka

# See the list of use/switch targets
perlbrew list

# Activate a lib in current shell
perlbrew use perl-5.12.3@shizuka
perlbrew use perl-5.14.2@nobita
perlbrew use perl-5.14.2@shizuka

# Activate a lib as default
perlbrew switch perl-5.12.3@shizuka
perlbrew switch perl-5.14.2@nobita
perlbrew switch perl-5.14.2@shizuka

# Delete lib perl-5.14.2@nobita and perl-5.14.2@shizuka
perlbrew use perl-5.14.2
perlbrew lib delete nobita
perlbrew lib delete shizuka

# Delete lib perl-5.12.3@shizuka
perlbrew lib delete perl-5.12.3@shizuka

Short lib names are local to the current perl. A lib name 'nobita' can refer to 'perl-5.12.3@nobita' or 'perl-5.14.2@nobita', whichever is activated in the current shell. So context matters, bestie. 🎀

When useing or switching to a lib, always provide the long name. A simple rule: the argument to the use or switch command should appear in the output of perlbrew list. If it's not on the list, it's not the vibe. 📝

🌈 COMMAND: UPGRADE-PERL 🌈

Usage:

perlbrew upgrade-perl

Running this command upgrades the currently activated perl to its latest released siblings. If you have a shell with 5.32.0 activated, it upgrades it to 5.32.1. Sibling glow-up!! 🫶

Minor Perl releases (ex. 5.x.*) are binary compatible with one another, so this command offers you the ability to upgrade older perlbrew environments in place. In place, no reinstall drama. 🔥

📥 COMMAND: DOWNLOAD 📥

Usage:

perlbrew download <perl-release>

Examples:

perlbrew download perl-5.14.2
perlbrew download perl-5.16.1
perlbrew download perl-5.17.3

Downloads the specified version of the perl distribution tarball under the directory $PERLBREW_ROOT/dists/.

The argument perl-release should be one of the items from the perlbrew available command. Don't make up names, it won't work. 😭

🧾 COMMAND: LIST-MODULES 🧾

Usage:

perlbrew list-modules

Lists all installed cpan modules for the current perl. Your whole module haul, itemised. 🛍️

This command can be used in conjunction with perlbrew exec to migrate your module installation to a different perl. The following command re-installs all modules under perl-5.16.0:

perlbrew list-modules | perlbrew exec --with perl-5.16.0 cpanm
Note that this installs the latest versions of the Perl modules on the new perl, which are not necessarily the same module versions you had installed previously. So it's a fresh install, not a time capsule. ⏳

🧬 COMMAND: CLONE-MODULES 🧬

Usage:

perlbrew clone-modules [options] <destination>
perlbrew clone-modules [options] <source> <destination>

Options:

  • --notest — Skip all module tests

This command re-installs all CPAN modules found from one installation to another. For example, this lists all modules under '5.26.1' and re-installs them under '5.27.7':

perlbrew clone-modules 5.26.1 5.27.7

The argument source is optional and defaults to the currently activated one. However, if none is activated (perlbrew is switched off), it is an error. 🚨

Note that this does not guarantee that the versions of modules stay the same in the destination. Close enough, but not identical twins. 👯

💅 COMMAND: MAKE-SHIM 🎀

Usage, bestie:

perlbrew make-shim <program>
perlbrew make-shim -o <shim-name> <program>
perlbrew make-shim --output <shim-name> <program>

Okay so this command literally makes an executable file in your current directory, named <program> — or <shim-name> if you passed it after --output (or -o for short, we love a short flag 💖). That output file is a shell-wrapper, a shim, of the named program living inside your current perlbrew environment.

When you run that shim, the original <program> gets executed with all the relevant environment variables set to the perlbrew environment it's installed in — and it does this regardless of which perlbrew environment is currently activated. Iconic. ✨ The shim can also be moved to other directories, like the conventional ~/.local/bin, so it's always available. Main character energy fr fr.

Say, for example, you find tldr from App::tldr to be a handy little tool and you decide to install it inside your daily working environment:

perlbrew use perl-5.36.1
cpm install -g App::tldr

But then you occasionally have to switch to a different environment, PATH gets tweaked, and the command tldr just... goes missing. And that's the expected outcome, ngl:

perlbrew use perl-5.18.4
tldr perl  #=> error: command not found

😭 the betrayal.

It would be nice if tldr could be made universally available. One way to mitigate such needs is to prepare install the tldr program outside of PERLBREW_ROOT, while still utilize perlbrew environment to run it. Lowkey genius.

For example, prepare a conventional directory ~/.local/bin and put that in PATH, then:

perlbrew use perl-5.36.1

cd /tmp
perlbrew make-shim tldr
mv /tmp/tldr ~/.local/bin/tldr

This ~/.local/bin/tldr is a shell-wrapper of the actual tldr program, and it internally activates the perlbrew environment perl-5.36.1. So running the tldr shim will always run the actual tldr, no matter which perlbrew environment is activated, or even if perlbrew is turned off. Slay. 👑

The only requirements is that the perlbrew environment perl-5.36.1 and the installation of App::tldr has to remain. Keep them, bestie, don't delete them. 🙈

🦋 COMMAND: MAKE-PP 🌈

Usage:

perlbrew make-pp -i <path> -o <path>
perlbrew make-pp --input <path> --output <path>

This command takes a path of a perl program (the input), and produce a PAR-packed version of that program to the specified path (the output). Essentially this is a wrapper of pp from PAR::Packer, hence the name. It's giving "it's literally pp but with make". 💅

This requires the current perlbrew environment to have PAR and PAR::Packer installed first. Otherwise make-pp bails out. 🚪💨 In addition, if the current perl is not a perlbrew-managed perl, or if the given output path is already occupied, <make-pp> also bails out.

The produced file is a standalone binary executable containing these content:

  1. The input perl program
  2. perl runtime
  3. all core perl libs of current perl
  4. the entire site lib
  5. the entire local lib (managed by `perlbrew lib` command), if active.

It is expected that the executable can then be running on a different machine of the same OS and arch. 🖥️✨

Noted that this approach is the maximum overkill for packing one program as it'll be definitely packaing a lot more then the exact list of runtime dependencies of the named program. make-pp is meant for a lazy solution for a non-trivial problem of perfectly determing the runtime dependencies of an arbitarary program.

And honestly? Respect. Sometimes you just wanna pack everything and not think about it. 🍓

🌸 SEE ALSO 🌸

  • App::perlbrew
  • App::cpanminus
  • Devel::PatchPerl

And that's the whole page, bestie!! 💖 You made it to the end, so proud of you fr fr. 🥹✨

This was perlbrew's manual, perl v5.40.1, dated 2025-10-03 — that's the PERLBREW(1p) page, and now it's officially in your brain forever. 🧠👑

go install something cute, love u, bye!! 🦋💅🎀

📦 where this page comes from