# App::perlbrew keeps every perl version inside your home directory

> perlbrew builds and installs perl interpreters under ~/perl5/perlbrew and manages them with switch, use, on and off, so that installing CPAN modules no longer needs sudo. The cost is a shell setup step and a self-upgrade path that does not cover every install method.

**gugod/App-perlbrew** — Manage perl installations in your $HOME

- Repository: https://github.com/gugod/App-perlbrew
- Website: https://perlbrew.pl
- Stars: 737 · Forks: 231
- Language: Perl
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/gugod-app-perlbrew

## A perl root inside $HOME instead of a system perl

The repository describes the tool in one line: "App::perlbrew - Manage perl installations in your $HOME". The mechanism behind that phrase is simple and worth stating plainly, because it decides everything else. Perlbrew builds and installs perl interpreters itself, places every one of them under `~/perl5/perlbrew`, and gives you commands to move between them. The README calls that directory the perlbrew root and says it will contain all installed perl executables, libraries, documentations, lib and site_libs.

The payoff for a developer is stated just as directly: because everything lands inside your HOME, you can install CPAN modules without running sudo commands, since those modules are installed inside your HOME too. The second consequence is that the shell needs adjusting. Perlbrew provides a bashrc or cshrc fragment to tweak your PATH, and the installer tells you to follow the on screen instructions to add it to your shell rc file. Two moving parts, then: a collection of interpreters under one directory, and a PATH edit so the shell finds them.

## The installer is a shell script you pipe into bash

Installation is one line, and the README is upfront that this is the simplest route:

```
        curl -L https://install.perlbrew.pl | bash
```

On systems that ship fetch instead of curl, by default on FreeBSD according to the README, the same thing works with:

```
        fetch -o- https://install.perlbrew.pl | sh
```

Afterwards perlbrew installs itself into `~/perl5/perlbrew/bin`, and you are asked to modify your shell rc file so that directory is on your PATH. Two details matter for planning. The installed `perlbrew` command is a standalone executable that runs with the system perl, and the minimum required system perl version is 5.8.0, which the README expects to cover most current operating systems. The installer also places a fat packed version of patchperl into `~/perl5/perlbrew/bin`, and that copy is required to build old perls. So the install step gives you two tools, not one.

## PERLBREW_ROOT lets a shared root work for several users

By default the root sits in your home directory, which raises an obvious question for teams on a shared machine. The README covers it: if your HOME has limited quota, or for any other reason, you can point the installer elsewhere by exporting `PERLBREW_ROOT` before running it:

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

The result is that different users on the same machine can share the same perlbrew root directory. The README attaches one condition, and it is the kind of detail that turns into a support ticket later: only the original user who made the installation has permission to perform perl installations. Everyone else can read and use the interpreters already there, but adding a new version remains the job of that first user.

There is a related setting for the interpreter perlbrew itself runs under. If you need to install using a perl that is neither `/usr/bin/perl` nor `/usr/local/bin/perl`, set and export `PERLBREW_SYSTEM_PERL` before installing. The README adds a constraint that is easy to break by accident: you must not point it at a perl that perlbrew manages.

## switch, use, on and off are four different states

Once interpreters exist, the interesting part is how you move between them. The synopsis shows the whole vocabulary:

```
        perlbrew init
        perlbrew available
        perlbrew install 5.32.1
        perlbrew install perl-5.28.3
        perlbrew list
        perlbrew switch perl-5.32.1
        perlbrew use perl-5.28.3
        perl -v
        perlbrew off
        perlbrew on
```

`perlbrew available` reports what can be installed and `perlbrew list` reports what has been installed, with version names written in two accepted forms, a bare version such as `5.32.1` and a prefixed one such as `perl-5.28.3`. The behavioural difference between the two switching commands is the part worth remembering. The README describes `switch` as switching to an installation and setting it as default, while `use` applies another version only in the current shell. `perl -v` after `use` is how you confirm which interpreter answered. `perlbrew off` turns the perlbrew environment off and returns you to the system perl, and `perlbrew on` turns it back on, with `switch` and `use` as the two ways of choosing a version again.

## exec runs a command across every brewed perl

One more command completes the set, and it is the one that saves the most time. The synopsis shows it as:

```
        perlbrew exec -- perl -E 'say $]'
```

The comment above it in the README describes the intent: running something with all perlbrew-ed perls. Instead of activating one version and repeating the command for each, `exec` iterates over the installed interpreters and runs the given command under each of them. That is how you would check that a module or a script behaves the same across the versions you care about, and it is a pattern that does not exist when you depend on the distribution perl alone.

Taken together with the switch and use commands, perlbrew offers three ways to point at a particular perl: make it the default, use it for one shell only, or run one command under all of them.

## Installing through cpan has its own upgrade trap

The installer script is only one route. The README also documents installing from CPAN:

```
        cpan App::perlbrew
```

In that case the `perlbrew` command lands somewhere on your system PATH, such as `/usr/bin/perlbrew` or `/usr/local/bin/perlbrew`, depending on where your system perl lives. Two warnings follow, and they are specific enough to be useful. First, never run the CPAN install with a perl that perlbrew itself manages, and if you are upgrading, turn perlbrew off first:

```
        perlbrew off
        cpan App::perlbrew
```

Second, the README says you should always use the system cpan, for example `/usr/bin/cpan`, to install App::perlbrew, because that installs under a system PATH such as `/usr/bin`, which is not affected by the perlbrew switch, use or on commands. The reason is the upgrade path. The self upgrade command will not upgrade a perlbrew that was installed through cpan, so upgrading that copy means running `cpan App::perlbrew` again by hand.

## The distribution alternative and what it costs you

The alternative to perlbrew is the arrangement most machines already have: one perl from the operating system, installed and updated by the distribution, with CPAN modules installed system wide using root privileges. The difference is not speed or convenience, it is scope. The distribution perl gives you exactly one version, changes only when the distribution changes it, and every module you add sits in a shared location that needs root access. Perlbrew moves that whole set inside a user owned directory, gives you several versions at once, and removes the need for sudo on module installs.

The price is a shell rc file edit, a directory of interpreters that consumes disk space, and the constraint that only the first user of a shared root can install new versions. For a laptop where you need to test an old release alongside a current one, that trade reads well. For a production server with a single blessed perl, a system package manager is usually the simpler answer.

## Where the code and the issue tracker live

The repository is organised like a CPAN distribution. At the top level are `Build.PL`, `cpanfile`, `META.json`, `META.yml`, `metamerge.json`, the `perlbrew` and `perlbrew-install` scripts, a `lib/` directory, a `script/` directory, and two test directories named `t/` and `test-e2e/`. Style tooling is configured through `.perlcriticrc` and `.perltidyrc`, continuous integration is configured in `.circleci/`, and there is a `Changes` file for release notes and a `SECURITY.md` for security policy.

The default branch is `develop`, not `master`, and the repository lists no GitHub releases, so tags on CPAN are where released versions appear. The homepage is https://perlbrew.pl, and the README says issue tracking runs through the GitHub issues page at https://github.com/gugod/App-perlbrew/issues, with contributing instructions in CONTRIBUTING.md. The README also points out that the main documentation is the `perlbrew` command page on MetaCPAN, and that the document you are reading covers the App::perlbrew module API and may not match what you want to read. The author is Kang-min Liu, the copyright notice reads 2023, and the licence section states the MIT License. The repository is not archived and the last push was on 2026-09-13.

## Conclusion

perlbrew suits developers who need more than one perl on one machine, who cannot or will not install modules with sudo, and who want a per user perl root rather than a shared system perl. It does not suit servers that need a single fixed perl managed by the distribution, nor anyone unwilling to edit a shell rc file. Verify first that your system perl is at least 5.8.0, that the installer can write to the chosen PERLBREW_ROOT, that PERLBREW_SYSTEM_PERL points at a real non managed interpreter if you set it, and that the perlbrew command on your PATH came from the installer rather than from cpan, since the self upgrade command will not update a cpan installed copy.

## FAQ

### Where does App::perlbrew install perl versions?

By default everything goes under ~/perl5/perlbrew, the directory the documentation calls the perlbrew root, which holds the perl executables, libraries, documentations, lib and site_libs. You can point the installer at another location by exporting PERLBREW_ROOT before running it.

### What is the difference between perlbrew switch and perlbrew use?

The README describes switch as switching to an installation and setting it as default, while use applies another version only in the current shell. `perlbrew off` returns to the system perl and `perlbrew on` turns the environment back on.

### Do I need sudo to install CPAN modules with perlbrew?

No. The README states that because modules are installed inside your HOME, you can install CPAN modules without running sudo commands. Installing the perl interpreters themselves is a separate step that perlbrew handles under the same root directory.

### How do I upgrade perlbrew after installing it from CPAN?

The self upgrade command will not upgrade a perlbrew installed through cpan, so you upgrade it by running `cpan App::perlbrew` again. The README also says to use the system cpan, and to run `perlbrew off` first, so that the install does not run under a perlbrew managed perl.

## Sources

- [gugod/App-perlbrew on GitHub](https://github.com/gugod/App-perlbrew)
- [Issues](https://github.com/gugod/App-perlbrew/issues)
- [Project website](https://perlbrew.pl)
- [README](https://github.com/gugod/App-perlbrew/blob/develop/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gugod-app-perlbrew