zef(1)

📦

version 0.13.8 · 2 versions

0.13.8 · debian trixie, ubuntu resolute, ubuntu stonking (latest)
0.13.8 · debian bookworm, ubuntu noble

, in debian trixie, ubuntu resolute, ubuntu stonking

✨ zef(1) — Raku user documentation ✨

okay so bestie, welcome to the zef(1) page straight from the Raku user documentation. This is the manual for the Raku / Perl6 module manager, and she is literally the main character of getting your modules where they need to be. No cap. 💅

✨ NAME ✨

zef — Raku / Perl6 Module Management 🫶

✨ SYNOPSIS ✨

Here's the whole vibe check, exactly as it is:

zef --help
zef --version

# install the CSV::Parser distribution
zef install CSV::Parser

# search for distribution names matching `CSV`
zef search CSV

# detailed information for a matching distribution
zef info CSV::Parser

# list all available distributions
zef list

# list reverse dependencies of an identity
zef rdepends HTTP::UserAgent

# test project in current directory
zef test .

# fetch a specific module only
zef fetch CSV::Parser

# fetch a module, then shell into its local path
zef look CSV::Parser

# smoke test modules from all repositories
zef smoke

# run Build.pm if one exists in given path
zef build .

# update Repository package lists
zef update

# upgrade all distributions (BETA)
zef upgrade

# upgrade specific distribution (BETA)
zef upgrade CSV::Parser

# lookup module info by name/path/sha1
zef --sha1 locate 9FA0AC28824EE9E5A9C0F99951CA870148AE378E

# launch browser to named support urls from meta data
zef browse zef bugtracker

✨ DESCRIPTION ✨

Zef is a package manager dedicated for Raku language. That's the whole plot, and she ate. 💖

✨ More CLI ✨

install [*@identities] 💖

Note: The install process does not install anything until all phases have completed. So, if the user requested to install A, and A required module B: both would be downloaded, potentially built, tested, and installed – but only if both passed all their tests. For example: if module A failed its tests, then module B would not be installed (even if it passed its own tests) unless forced. 🫣

[@identities] can take the form of a file path (starting with . or /), URLs, paths, or identities:

# IDENTITY
zef install CSV::Parser
zef install "CSV::Parser:auth<tony-o>:ver<0.1.2>"
zef install "CSV::Parser:ver<0.1.2>"

# PATH
zef install ./Perl6-Net--HTTP

# URL
zef -v install https://github.com/ugexe/zef.git
zef -v install https://github.com/ugexe/zef/archive/master.tar.gz
zef -v install https://github.com/ugexe/zef.git@v0.1.22

A request may contain any number and combination of these. Paths and URLs will be resolved first so they are available to fulfill any dependencies of other requested identities. 💅

Options

--install-to=<id> — install to a custom location. <id> can be site/home/vendor/perl, or
-to=<id> — the short form, like inst#/home/some/path/custom
--contained — install all transitive and direct dependencies even if they are already installed globally (BETA)
--config-path=/some/path/config.json — load a specific Zef config file
--deps-only — install only the dependency chains of the requested distributions
--force-resolve — ignore errors occurring during the resolve phase
--force-fetch — ignore errors occurring during the fetch phase
--force-extract — ignore errors occurring during the extract phase
--force-build — ignore errors occurring during the build phase
--force-test — ignore errors occurring during the test phase
--force-install — ignore errors occurring during the install phase
--force — or set the default to all unset --force-* flags to True
--fetch-timeout=600 — set the timeout for the fetch phase
--extract-timeout=3600 — set the timeout for the extract phase
--build-timeout=3600 — set the timeout for the build phase
--test-timeout=3600 — set the timeout for the test phase
--install-timeout=3600 — set the timeout for the install phase
--fetch-degree=5 — number of simultaneous distributions/jobs to process for the fetch phase
--test-degree=1 — number of simultaneous distributions/jobs to process for the test phase
--timeout=0 — or set the default to all unset --*-timeout flags to 0
--dry — do everything except the actual installations
--serial — build/test/install each dependency serially before proceeding to build/test/install the next
--/test — disable testing
--/build — disable build phase
--/depends — disable fetching dependencies
--/build-depends — disable fetching build dependencies
--/test-depends — disable fetching test dependencies
--update — force a refresh for all module index indexes
--update=[ecosystem] — force a refresh for a specific ecosystem module index
--/update — skip refreshing all module index indexes
--/update=[ecosystem] — skip refreshing for a specific ecosystem module index

ENV Options

ZEF_FETCH_DEGREE=5 — number of simultaneous distributions/jobs to process for the fetch phase (see --[phase]-degree options)
ZEF_TEST_DEGREE=1 — number of simultaneous distributions/jobs to process for the test phase (see --[phase]-degree options)
ZEF_FETCH_TIMEOUT=600 — set the timeout for the fetch phase (see --[phase]-timeout options)
ZEF_EXTRACT_TIMEOUT=3600 — set the timeout for the extract phase (see --[phase]-timeout options)
ZEF_BUILD_TIMEOUT=3600 — set the timeout for the build phase (see --[phase]-timeout options)
ZEF_TEST_TIMEOUT=3600 — set the timeout for the test phase (see --[phase]-timeout options)
ZEF_INSTALL_TIMEOUT=3600 — set the timeout for the install phase (see --[phase]-timeout options)
ZEF_CONFIG_PATH=$PWD/resources/config.json — path to config file (see --config-path option)

uninstall [*@identities] 🗑️

Uninstall the specified distributions.

Note: Requires a bleeding edge rakudo (not available in 6.c) 💀

update 🔄

Update the package indexes for all Repository backends.

Note: Some Repository backends, like the default Ecosystems, have an auto-update option in resources/config.json that can be enabled. This should be the number of hours until it should auto update based on the file system last modified time of the ecosystem json file location.

upgrade [*@identities] BETA 🚀

Upgrade specified identities. If no identities are provided, zef attempts to upgrade all installed distributions.

search [$identity] 🔎

How these are handled depends on the Repository engine used, which by default is Zef::Repository::Ecosystems>p6c<.

$ zef -v search URI
===> Found 4 results
-------------------------------------------------------------------------
ID|From                              |Package             |Description
-------------------------------------------------------------------------
1 |Zef::Repository::LocalCache       |URI:ver<0.1.1>    |A URI impleme...
2 |Zef::Repository::Ecosystems<p6c>  |URI:ver<0.1.1>    |A URI impleme...
3 |Zef::Repository::Ecosystems<cpan> |URI:ver<0.1.1>    |A URI impleme...
4 |Zef::Repository::Ecosystems<cpan> |URI:ver<0.000.001>|A URI impleme...
-------------------------------------------------------------------------

info [$identity] 🧐

View meta information of a distribution.

$ zef -v info HTTP::UserAgent
- Info for: HTTP::UserAgent
- Identity: HTTP::UserAgent:ver<1.1.16>:auth<github:sergot>
- Recommended By: Zef::Repository::LocalCache
Author:  github:sergot
Description:     Web user agent
Source-url:      https://github.com/sergot/http-useragent.git
Provides: 11 modules
#       HTTP::Cookie
#       HTTP::Header
#       HTTP::Cookies
#       HTTP::Message
#       HTTP::Request
#       HTTP::Response
#       HTTP::MediaType
#       HTTP::UserAgent
#       HTTP::Header::Field
#       HTTP::Request::Common
#       HTTP::UserAgent::Common
Depends: 7 items
---------------------------------
ID|Identity           |Installed?
---------------------------------
1 |HTTP::Status       |✓
2 |File::Temp         |✓
3 |DateTime::Parse    |✓
4 |Encode             |✓
5 |MIME::Base64       |✓
6 |URI                |✓
7 |IO::Capture::Simple|✓
---------------------------------

Options

-v — extra details (eg, list dependencies and which ones are installed)

list [*@from] 📋

List known available distributions.

$ zef --installed list
===> Found via /home/foo/.rakubrew/moar-master/install/share/perl6/site
CSV::Parser:ver<0.1.2>:auth<github:tony-o>
Zef:auth<github:ugexe>
===> Found via /home/foo/.rakubrew/moar-master/install/share/perl6
CORE:ver<6.c>:auth<perl>

Note that not every Repository may provide such a list, and such lists may only be a subset. For example: We may not be able to get a list of every distribution on cpan, but we can get the $x most recent additions (we use 100 for now).

[@from] allows you to show results from specific repositories only:

zef --installed list perl   # Only list modules installed by rakudo itself

zef list cpan               # Only show available modules from the repository
zef list p6c                # with a name field matching the arguments to `list`
zef list cached             # (be sure the repository is enabled in config)

Otherwise results from all enabled repositories will be returned.

Options

--installed — only list installed distributions
-v — additionally list the modules of discovered distributions

depends [$identity] 🔗

List direct and transitive dependencies to the first successful build graph for $identity.

$ zef depends Cro::SSL
Cro::Core:ver<0.7>
IO::Socket::Async::SSL:ver<0.3>
OpenSSL:ver<0.1.14>:auth<github:sergot>

rdepends [$identity] ↩️

List available distributions that directly depend on $identity.

$ zef rdepends Net::HTTP
Minecraft-Tools:ver<0.1.0>
LendingClub:ver<0.1.0>

fetch [*@identities] 📥

Fetches candidates for given identities.

test [*@paths] 🧪

Run tests on each distribution located at [@paths].

build [*@paths] 🛠️

Run the Build.pm file located in the given [@paths].

If you want to create a build hook, put the following dependency-free boilerplate in a file named Build.pm at the root of your distribution:

class Build {
    method build($dist-path) {
        # do build stuff to your module
        # which is located at $dist-path
    }
}

Set the env variable ZEF_BUILDPM_DEBUG=1 or use the –debug flag for additional debugging information.

Note: In the future, a more appropriate hooking solution will replace this.

look [$identity] 👀

Fetches the requested distribution and any dependencies (if requested), changes the directory to that of the fetched distribution, and then stops program execution. This allows you modify or look at the source code before manually continuing the install via zef install .

Okay so real talk — the path to any dependencies that had to get fetched will be set in env at RAKULIB, so you can run any build scripts, run tests, or do a whole manual install without ever having to spell out where they live. Convenient. Iconic. 💅

🦋 `browse $identity [bugtracker | homepage | source]`

Options

--/open — turns OFF the browser-launching (so it just shows you the url, no window popping off)

This one prints the url and yeets a browser open to it. Both at once. Multitasking queen.

# also opens browser
$ zef browse Net::HTTP bugtracker
https://github.com/ugexe/Perl6-Net--HTTP/issues

# only outputs the url
$ zef browse Net::HTTP bugtracker --/open
https://github.com/ugexe/Perl6-Net--HTTP/issues

🔍 `locate [$identity, $name-path, $sha1-id]`

Options

--sha1 — tells zef the argument is a sha1-id (otherwise it just assumes it's an identity or a name-path)

Looks up a locally installed module by $identity, $name-path, or $sha1-id. Three ways in, one cute little lookup. ✨

$ zef --sha1 locate A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
lib/Zef/CLI.rakumod => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31

$ zef locate Zef::CLI
===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
lib/Zef/CLI.rakumod => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31

$ zef locate lib/Zef/CLI.rakumod
===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
Zef::CLI => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31

💀 `nuke [RootDir | TempDir | StoreDir]`

Deletes all the paths in the specific configuration directory you point at. All of them. Every single path. No survivors. 🙈

💀 `nuke [site | home]`

Deletes all paths that are rooted in the prefix of the matching CompUnit::Repository name.

# uninstall all modules
$ zef nuke site home

bestie this is the uninstall everything button. Please be so serious when you type it. 😭

🔊 Output Verbosity

You get to control the logging level with these flags, bestie:

# More/less detailed output
--error, --warn, --info (default), --verbose (-v), --debug

So --error is giving "only scream if it's bad", and --debug is giving "tell me EVERYTHING, main character energy". --info is the default because balance. 🧘

💖 Global Configuration 💖

📂 Finding the configuration file

You can always see which configuration file is gonna be used by running:

$ zef --help

For most people, the default config plus whatever command line options you pass is plenty. Full stop.

If you are most people (aka: not a power user, not a packager, not a zef plugin dev), then hopefully you simply do not care about this section! And that's valid. 🫶

🧚 How the configuration file is chosen

The configuration file gets picked at runtime out of one of two (technically four 👀) locations, and one of them can affect the others. Yes this is a whole thing — the manpage itself says it's not really a design decision and that suggestions and PRs are welcome. So if you have opinions, slay, send them in.

First, and the most precise way: specify the config file directly by passing --config-path="..." to any zef command.

Second, third, and fourth, we look at the path that %?RESOURCES<config.json> points to. That'll point to $zef-dir/resources/config.json, where $zef-dir is one of these three:

The prefix of a common configuration directory, such as $XDG_CONFIG_HOME or $HOME/.config.
The prefix of a rakudo installation location — this is the case when the modules loaded for bin/zef come from an installation CompUnit::Repository.
The current working directory $*CWD — this is the case when the modules loaded for bin/zef come from a non-installation CompUnit::Repository (like -I $dist-path).

To understand how this gets chosen, consider:

# Modules not loaded from an ::Installation,
# so %?RESOURCES is $*CWD/resources
$ raku -I. bin/zef --help
...
CONFIGURATION /home/user/raku/zef/resources/config.json
...

# Installed zef script loads modules from an ::Installation,
# so %?RESOURCES is $raku-share-dir/site/resources
$ zef --help
...
CONFIGURATION /home/user/raku/install/share/perl6/site/resources/EE5DBAABF07682ECBE72BEE98E6B95E5D08675DE.json
...

Okay so this config gets loaded, but plot twist — it is not yet the chosen config! We check that temporary config's %config<RootDir> for valid json in a file named config.json (i.e. %config<RootDir>/config.json). Yeah, the manpage admits this can be confusing and that it may go away or get refined (PRs welcome, again, they're begging). But for most cases it just means $*HOME/.zef/config.json will override an installed zef configuration file.

To summarize:

You can edit the resources/config.json file before you install zef.

When you run raku -I. bin/zef install . that configuration file will be used to install zef, and it will also be installed along with zef so that it becomes the default.

You can create a %config<RootDir>/config.json file.

Where %config<RootDir> comes from the RootDir field of the previously mentioned %?RESOURCES<config.json> ($*HOME/.zef in most cases), so that you can override zef's config behavior on a per-user basis — which lets you set different --install-to targets for, say, a root user and a regular user. And since this new config file could have a different RootDir than the default config (which was used to find the new one in the first place), this behavior may get changed in the future to be less confusing.

You can override both of the previous entries by passing zef --config-path="$path" <any command>.

🛠️ Configuration fields

🌱 Basic Settings

RootDir — where zef will look for a custom config.json file
TempDir — a staging area for items that have been fetched and need to be extracted/moved
StoreDir — where zef caches distributions, package lists, etc. after they've been fetched and extracted
DefaultCUR — this sets the default value for --install-to="...". The default value is auto, which means it will first try installing to rakudo's installation prefix, and if that isn't writable by the current user it'll install to $*HOME/.raku. These directories aren't chosen by zef — they're actually represented by the magic strings site and home (which, just like auto, are valid values despite not being paths, alongside vendor and perl).

🔌 Phases / Plugins Settings

These are an array of hashes that describe how to instantiate some class that fulfills the appropriate interface from Zef.pm (Repository Fetcher Extractor Builder Tester Reporter). Yes, that's a whole roster. 👑

The descriptions follow this format:

{
    "short-name" : "p6c",
    "enabled" : 1,
    "module" : "Zef::Repository::Ecosystems",
    "options" : { }
}

and they're instantiated via

::($hash<module>).new(|($hash<options>)

short-name — this adds an enable and disable flag by the same name to the CLI (e.g. --p6c and --/p6c) and is used when referencing which object took some action.
enabled — set it to 0 to skip over the object during consideration (it will never be loaded). If it's omitted, or if the value is non 0, then it'll be enabled for use.
module — the name of the class to instantiate. While it doesn't technically have to be a module, it does need to be a known namespace to require.
options — these get passed to the object's new method, and they may not be consistent between modules since modules are free to implement their own requirements.

See the configuration file in resources/config.json for a little more information on how plugins are invoked.

You can see debug output related to choosing and loading plugins by setting the env variable ZEF_PLUGIN_DEBUG=1. 🔍

❓ FAQ

🌐 Proxy support?

All the default fetching plugins have proxy support, but you'll need to refer to the backend program's docs (wget, curl, git, etc). You may need to set an ENV variable, or you may need to add a command line option for that specific plugin in resources/config.json.

📦 Custom installation locations?

Pass a path to the -to / --install-to option and prefix the path with inst# (unless you know what you're doing 👀).

$ zef -to="inst#/home/raku/custom" install Text::Table::Simple
===> Searching for: Text::Table::Simple
===> Testing: Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>
===> Testing [OK] for Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>
===> Installing: Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>

To make that custom location discoverable:

# Set the RAKULIB env:
$ RAKULIB="inst#/home/raku/custom" raku -e "use Text::Table::Simple; say 'ok'"
ok

# or simply include it as needed
$ raku -Iinst#/home/raku/custom -e "use Text::Table::Simple; say 'ok'"
ok

And that's a wrap on the zef(1) manual page, bestie 💖 that's the whole thing, from top to bottom. Go install something cute with it. 🎀✨

📦 where this page comes from

debian trixie: raku-zef 0.13.8-4 · Artistic-2.0
ubuntu resolute: raku-zef 0.13.8-4 · Artistic-2.0
ubuntu stonking: raku-zef 0.13.8-4 · Artistic-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms

zef(1)

✨ zef(1) — Raku user documentation ✨

✨ NAME ✨

✨ SYNOPSIS ✨

✨ DESCRIPTION ✨

✨ More CLI ✨

install [*@identities] 💖

Options

ENV Options

uninstall [*@identities] 🗑️

update 🔄

upgrade [*@identities] BETA 🚀

search [$identity] 🔎

info [$identity] 🧐

Options

list [*@from] 📋

Options

depends [$identity] 🔗

rdepends [$identity] ↩️

fetch [*@identities] 📥

test [*@paths] 🧪

build [*@paths] 🛠️

look [$identity] 👀

🦋 browse $identity [bugtracker | homepage | source]

🔍 locate [$identity, $name-path, $sha1-id]

💀 nuke [RootDir | TempDir | StoreDir]

💀 nuke [site | home]

🔊 Output Verbosity

💖 Global Configuration 💖

📂 Finding the configuration file

🧚 How the configuration file is chosen

🛠️ Configuration fields

🌱 Basic Settings

🔌 Phases / Plugins Settings

❓ FAQ

🌐 Proxy support?

📦 Custom installation locations?

🦋 `browse $identity [bugtracker | homepage | source]`

🔍 `locate [$identity, $name-path, $sha1-id]`

💀 `nuke [RootDir | TempDir | StoreDir]`

💀 `nuke [site | home]`