ZKG(1)

📦

version 3.1.0 · 5 versions

3.1.0 · ubuntu resolute, ubuntu stonking (latest)
2.12.0 · ubuntu jammy
2.14.0 · ubuntu noble
2.13.0 · debian bookworm
3.0.1 · debian trixie, ubuntu questing

✨ NAME ✨

zkg — Zeek Package Manager 👑

A command-line package manager for Zeek. That's the whole vibe bestie: it's the thing that grabs your Zeek packages, installs them, and keeps them organized so you're not out here cloning repos by hand like a medieval peasant 💀

usage: zkg [-h] [--version] [--configfile FILE | --user] [--verbose] [--extra-source NAME=URL]
           {test,install,bundle,unbundle,remove,uninstall,purge,refresh,upgrade,load,unload,pin,unpin,list,search,info,config,autoconfig,env,create,template}
           ...

🎀 Options 🎀

--version — shows the program's version number and then dips out 👋
--configfile — the path to the Zeek Package Manager config file. Heads up: this one precludes --user. They cannot coexist, it's giving exes at the same party 💀 See Config File.
--user=False — stores all state in your home directory. Also precludes --configfile. Same energy, opposite direction.
--verbose=0, -v=0 — bumps up the program output for debugging. Use it multiple times for even more output (like -vv). Stack it, it's additive ✨
--extra-source — adds an extra source. More sources, more packages, no cap 🫶

🌈 Environment Variables 🌈

ZKG_CONFIG_FILE: same thing as the --configfile option, except it has less precedence. iykyk.
ZKG_DEFAULT_SOURCE: the default package source to use — normally https://github.com/zeek/packages.
ZKG_DEFAULT_TEMPLATE: the default package template to use — normally https://github.com/zeek/package-template.

👑 COMMANDS 👑

🧪 test

Runs the unit tests for the specified Zeek packages. Fair warning bestie: in most cases the "zeek" and "zeek-config" programs need to be in your PATH before you run this command 🌸

usage: zkg test [-h] [--version VERSION] package [package ...]

Positional arguments

package — the name(s) of the package(s) to operate on. And okay so, a package can be named in several different ways:
- if the package is part of a package source, you can refer to it by the base name of the package (that's the last component of its git URL) or by its path within the package source.
- if two packages in different package sources have conflicting paths, you can prepend the package source name to the package path to resolve the ambiguity.
- a full git URL also works, for pointing at a package that doesn't belong to a source at all.

So like, for a package source called "zeek" that has a package named "foo" located in "alice/zkg.index", all of these names work: "foo", "alice/foo", "zeek/alice/foo". Slay 💅

Options

--version — the version of the package to test. ⚠️ Only one package may be specified at a time when you use this flag. You can drop a version tag, a branch name, or a commit hash in here. If the package name refers to a local git repo with a working tree, then its currently active branch gets used. For other cases, the default is the latest version tag — or, if the package has none, the default branch, like "main" or "master".

📦 install

Installs packages from a configured package source, or directly from a git URL. After installing, the package gets marked as being "loaded" (peep the load command for that one). ✨

usage: zkg install [-h] [--skiptests] [--nodeps] [--nosuggestions] [--version VERSION] [--force]
                   [--user-var NAME=VAL]
                   package [package ...]

Positional arguments

package — the name(s) of the package(s) to operate on. There are several ways to name a package, fr fr:
- if the package is part of a package source, refer to it by the base name of the package (last component of the git URL) or by its path within the package source.
- if two packages in different package sources have conflicting paths, prepend the package source name to the package path and the ambiguity is resolved.
- a full git URL also works, for a package that doesn't belong to a source.

Example time: for a package source called "zeek" with a package named "foo" located in "alice/zkg.index", these names all work: "foo", "alice/foo", "zeek/alice/foo". 🦋

Options

--skiptests=False — skips running the unit tests for packages before installation. Living dangerously, love that for you.
--nodeps=False — skips all dependency resolution/checks.

⚠️ Using this option risks putting your installed package collection into a broken or unusable state. Not a cute look bestie, seriously.

--nosuggestions=False — skips automatically installing suggested packages.
--version — the version of the package to install. ⚠️ Only one package may be specified at a time when you use this flag. A version tag, a branch name, or a commit hash all go here. If the package name refers to a local git repo with a working tree, then its currently active branch is used. For other cases the default is the latest version tag — or, if the package has none, the default branch, like "main" or "master".
--force=False — doesn't prompt for confirmation or user variables. Zero questions, straight to business 💅
--user-var — a user variable assignment. This avoids prompting for input and lets you provide a value while using --force. Use it repeatedly as needed for multiple values.

🗑️ remove

Unloads (see the unload command 👀) and uninstalls a package you installed earlier.

usage: zkg remove [-h] [--force] [--nodeps] package [package ...]

Positional arguments

package — the name(s) of the package(s) to operate on. And yes, a package may be named in several ways:
- if it's part of a package source, use the base name of the package (last component of the git URL) or its path within the package source.
- if two packages in different package sources have conflicting paths, prepend the package source name to the package path to sort out the ambiguity.
- a full git URL also works, for a package that isn't part of a source.

For a package source called "zeek" with a package named "foo" in "alice/zkg.index", these all work: "foo", "alice/foo", "zeek/alice/foo". 🌸

Options

--force=False — skips the confirmation prompt.
--nodeps=False — skips all dependency resolution/checks.

⚠️ Using this option risks putting your installed package collection into a broken or unusable state. 💀

NOTE: You may also say uninstall.

🧹 purge

Unloads (see the unload command) and uninstalls all previously installed packages. Everything. Gone. Iconic.

usage: zkg purge [-h] [--force]

Options

--force=False — skips the confirmation prompt.

🎁 bundle

This command creates a bundle file containing a collection of Zeek packages. If --manifest is used, you supply the list of packages to put in the bundle — otherwise all currently installed packages go in the bundle. A bundle file can be unpacked on any target system, which results in a repeatable/specific set of packages being installed on that target system (see the unbundle command). This command may be useful for those who want to manage packages on a system that otherwise has limited network connectivity. E.g. you can use a system with an internet connection to create a bundle, transport that bundle over to the target machine using whatever means are appropriate, and finally unbundle/install it on the target machine. Chef's kiss 👑

usage: zkg bundle [-h] [--force] [--nodeps] [--nosuggestions] [--manifest MANIFEST [MANIFEST ...] --]
                  filename.bundle

Positional arguments

filename.bundle — the path of the bundle file to create. It will be overwritten if it already exists. And heads up: if --manifest is used before this filename is specified, you should use a double-dash, --, to first terminate that argument list. Yes, really.

Options

--force=False — skips the confirmation prompt.
--nodeps=False — skips all dependency resolution/checks.

⚠️ Using this option risks creating a bundle of packages that is in a broken or unusable state.

--nosuggestions=False — skips automatically bundling suggested packages.
--manifest — this may either be a file name or a list of packages to include in the bundle. If a file name is supplied, it should be in INI format with a single [bundle] section. The keys in that section correspond to package names and their values correspond to git version tags, branch names, or commit hashes. The values may be left blank to indicate that the latest available version should be used.

🪄 unbundle

This command unpacks a bundle file that was formerly created by the bundle command, and installs all the packages contained within it. It's giving unboxing video, but make it infrastructure ✨

usage: zkg unbundle [-h] [--replace] [--force] [--user-var NAME=VAL] filename.bundle

Positional arguments

filename.bundle — the path of the bundle file to install.

Options

--replace=False — using this flag first removes all installed packages before then installing the packages from the bundle. Clean slate energy.
--force=False — doesn't prompt for confirmation or user variables.
--user-var — a user variable assignment. This avoids prompting for input and lets you provide a value while using --force. Use it repeatedly as needed for multiple values.

🔄 refresh

Retrieves the latest package metadata from sources and checks whether any installed packages have available upgrades. Important: this does not actually upgrade any packages (see the upgrade command for that, bestie, that's a whole separate thing).

usage: zkg refresh [-h] [--aggregate] [--fail-on-aggregate-problems] [--push]
                   [--sources SOURCES [SOURCES ...]]

Options

🌈💖🎀🦋

--aggregate=False — bestie this one crawls every url in the package source's zkg.index files and scoops up all the metadata it finds in their zkg.meta (or the legacy bro-pkg.meta) files 💖. All that aggregated metadata gets stashed in the local clone of the package source that zkg keeps internally for finding package metadata. For each package, the metadata comes from the highest available git version tag — or from the default branch like main or master if there are literally no version tags at all ✨
--fail-on-aggregate-problems=False — when you're running with --aggregate, this makes zkg exit with an error if any packages trigger metadata problems. Normally those problems are just a lil warning, nbd 🙈
--push=False — pushes all your local changes to package sources up to the upstream repos 👑
--sources — a list of package source names to operate on. If you don't use this argument, the command operates on all configured sources 🌈

🌸 upgrade 🌸

Upgrades the specified package(s) to the latest available version 💅. If you don't name any specific packages, then every installed package that's outdated and not pinned gets upgraded. Here's the vibe: for packages installed with --version using a git branch name, the package gets updated to the latest commit on that branch — otherwise it's updated to the highest available git version tag ⭐

usage: zkg upgrade [-h] [--skiptests] [--nodeps] [--nosuggestions] [--force] [--user-var NAME=VAL]
                   [package ...]

Positional arguments

package — the name(s) of package(s) to operate on 🫶. And okay so a package can be named in several ways. If it's part of a package source, you can refer to it by the base name of the package (the last component of the git URL) or by its path within the package source. If two packages in different package sources have conflicting paths, you can prepend the package source name to the package path to clear up the ambiguity. A full git URL also works for referring to a package that doesn't belong to a source at all. E.g. for a package source called zeek that has a package named foo located in alice/zkg.index, these names all work: foo, alice/foo, zeek/alice/foo ✨

Options

--skiptests=False — skip running unit tests for packages before installation 🧚
--nodeps=False — skip all dependency resolution/checks. And listen, using this option risks putting your installed package collection into a broken or unusable state 💀 so like, be careful bestie
--nosuggestions=False — skip automatically installing suggested packages 🙈
--force=False — don't prompt for confirmation or user variables. No thoughts, just vibes 🔥
--user-var — a user variable assignment. This avoids prompting for input and lets you provide a value when using --force. Use it repeatedly as needed for multiple values 💜

🌈 load 🌈

The Zeek Package Manager keeps track of all packages marked as "loaded" and maintains a single Zeek script that — when loaded by Zeek (e.g. via @load packages) — will load the scripts from all the "loaded" packages at once 👑. This command adds a set of packages to the "loaded packages" list 💖

usage: zkg load [-h] [--nodeps] package [package ...]

Positional arguments

package — name(s) of package(s) to load 🌸

Options

--nodeps=False — skip all dependency resolution/checks. Note that using this option risks putting your installed package collection into a broken or unusable state 💀

🦋 unload 🦋

The Zeek Package Manager keeps track of all packages marked as "loaded" and maintains a single Zeek script that — when loaded by Zeek — will load the scripts from all the "loaded" packages at once ✨. This command removes a set of packages from the "loaded packages" list 🙈

usage: zkg unload [-h] [--force] [--nodeps] package [package ...]

Positional arguments

package — the name(s) of package(s) to operate on 🫶. The package may be named in several ways. If the package is part of a package source, it may be referred to by the base name of the package (last component of git URL) or its path within the package source. If two packages in different package sources have conflicting paths, then the package source name may be prepended to the package path to resolve the ambiguity. A full git URL may also be used to refer to a package that does not belong to a source. E.g. for a package source called zeek that has a package named foo located in alice/zkg.index, the following names work: foo, alice/foo, zeek/alice/foo 💜

Options

--force=False — skip the confirmation prompt. We're doing it live 🔥
--nodeps=False — skip all dependency resolution/checks. Note that using this option risks putting your installed package collection into a broken or unusable state 💀

💅 pin 💅

Pinned packages are ignored by the upgrade command. That's the whole point, iconic behaviour honestly 👑

usage: zkg pin [-h] package [package ...]

Positional arguments

package — the name(s) of package(s) to operate on 🫶. The package may be named in several ways. If the package is part of a package source, it may be referred to by the base name of the package (last component of git URL) or its path within the package source. If two packages in different package sources have conflicting paths, then the package source name may be prepended to the package path to resolve the ambiguity. A full git URL may also be used to refer to a package that does not belong to a source. E.g. for a package source called zeek that has a package named foo located in alice/zkg.index, the following names work: foo, alice/foo, zeek/alice/foo ✨

🎀 unpin 🎀

Packages that are not pinned are automatically upgraded by the upgrade command 🌸

usage: zkg unpin [-h] package [package ...]

Positional arguments

package — the name(s) of package(s) to operate on 🫶. The package may be named in several ways. If the package is part of a package source, it may be referred to by the base name of the package (last component of git URL) or its path within the package source. If two packages in different package sources have conflicting paths, then the package source name may be prepended to the package path to resolve the ambiguity. A full git URL may also be used to refer to a package that does not belong to a source. E.g. for a package source called zeek that has a package named foo located in alice/zkg.index, the following names work: foo, alice/foo, zeek/alice/foo 💜

🌟 list 🌟

Outputs a list of packages that match a given category ✨

usage: zkg list [-h] [--nodesc] [--include-builtin] [{all,installed,not_installed,loaded,unloaded,outdated}]

Positional arguments

category — package category used to filter the listing 🫶

Possible choices: all, installed, not_installed, loaded, unloaded, outdated

Options

--nodesc=False — do not display description text, just the package name(s). Minimalist era 💅
--include-builtin=False — also output packages that Zeek has built-in. By default these are not shown 🙈

🔍 search 🔍

Performs a substring search on package names and metadata tags ✨. Surround your search text with slashes to indicate it's a regular expression (e.g. /text/) 💖

usage: zkg search [-h] search_text [search_text ...]

Positional arguments

search_text — the text(s) or pattern(s) to look for 👑

🫶 info 🫶

Shows detailed information/metadata for the given packages 💜. If the package is currently installed, you also get extra info about its status — like the installed version, or whether it's currently marked as "pinned" or "loaded" ✨

usage: zkg info [-h] [--version VERSION] [--nolocal] [--include-builtin] [--json] [--jsonpretty SPACES]
                [--allvers]
                package [package ...]

Positional arguments

package — the name(s) of package(s) to operate on 🫶. The package may be named in several ways. If the package is part of a package source, it may be referred to by the base name of the package (last component of git URL) or its path within the package source. If two packages in different package sources have conflicting paths, then the package source name may be prepended to the package path to resolve the ambiguity. A full git URL may also be used to refer to a package that does not belong to a source. E.g. for a package source called zeek that has a package named foo located in alice/zkg.index, the following names work: foo, alice/foo, zeek/alice/foo 🌸. And plot twist: if you give a single name and it matches one of the same categories as the list command, then it's automatically expanded to be the names of all packages which match that given category 😭

Options

--version — the version of the package metadata to inspect 🧚. A version tag, branch name, or commit hash — and only one package at a time may be given when using this flag. If you don't specify it, the behaviour depends on whether the package is currently installed. If it's installed, the metadata is pulled from the installed version. If it's not installed, the latest version tag is used — or, if a package has no version tags, the default branch like main or master is used ✨
--nolocal=False — do not read information from locally installed packages. Instead, read info from remote GitHub 👑
--include-builtin=False — this one also shows you the packages that Zeek has built-in. bestie, by default those stay hidden, so if you're like "where are my builtins??" — this is the flag. 💅
--json=False — spits the package info out as JSON instead of the usual pretty little text. machine-readable era ✨
--jsonpretty — optional number of spaces to indent that pretty-printed JSON output. how much do you want it to breathe.
--allvers=False — when you're doing JSON output, this shows metadata for all versions. ⚠️ heads up: this option can be slow since remote repositories may get cloned multiple times. also, installed packages will show metadata only for the installed version unless the --nolocal option is given.

🛠 config

The default output of this command is a valid package manager config file that corresponds to the one currently being used — but with any defaulted field values filled in too. 🎀 It also lets you output just the value of one specific field, if you hand the name of that field over as an argument.

usage: zkg config [-h] [{all,sources,user_vars,state_dir,script_dir,plugin_dir,bin_dir,zeek_dist}]

Positional arguments:

config_param — name of a specific config file field to output.
- Possible choices: all, sources, user_vars, state_dir, script_dir, plugin_dir, bin_dir, zeek_dist

🌸 autoconfig

The output of this command is a valid package manager config file that gets generated by using the zeek-config script that's installed alongside Zeek. It's the suggested configuration for most Zeek installations, no cap. For this command to work, the zeek-config script must be in PATH — unless the --user option is given, in which case this creates a config that does not touch the Zeek installation. 🫶

usage: zkg autoconfig [-h] [--force]

Options:

--force=False — skips any confirmation prompt. bold move, iconic.

🌈 env

This command returns shell commands that, when executed, will correctly set ZEEKPATH and ZEEK_PLUGIN_PATH so you use scripts and plugins from packages installed by the package manager. ✨ For it to function properly, either have the zeek-config script (installed by zeek) in PATH, or have the ZEEKPATH and ZEEK_PLUGIN_PATH environment variables already set so this command can append package-specific paths onto them.

usage: zkg env [-h]

🎀 create

This command creates a new Zeek package in the directory you provide via --packagedir. If that directory already exists, zkg will not modify it unless you provide --force. 😌

usage: zkg create [-h] --packagedir DIR [--version VERSION] [--features FEATURE [FEATURE ...]]
                  [--template URL] [--force] [--user-var NAME=VAL]

Options:

--packagedir — output directory into which to produce the new package. Required. (like, you literally have to.)
--version — the template version to use. A version tag, branch name, or commit hash may be specified here. If --template refers to a local git repo with a working tree, then zkg uses it as-is and the version is ignored. The default for other cases is to use the latest version tag, or if a template has none, the default branch, like main or master.
--features — additional features to include in your package. Use the template info command for information about available features. 👑
--template — by default, zkg uses its own package template. This makes it select an alternative.
--force=False — don't prompt for confirmation or user variables.
--user-var — a user variable assignment. This avoids prompting for input and lets you provide a value when using --force. Use it repeatedly as needed for multiple values. 🍓

💜 template info

This command shows versions and supported features for a given package.

usage: zkg template info [-h] [--json] [--jsonpretty SPACES] [--version VERSION] [URL]

Positional arguments:

URL — URL of a package template repository, or local path to one. When not provided, the configured default template is used.

Options:

--json=False — output template information as JSON.
--jsonpretty — optional number of spaces to indent for pretty-printed JSON output.
--version — the template version to report on. A version tag, branch name, or commit hash may be specified here. If the selected template refers to a local git repo, the version is ignored. The default for other cases is to use the latest version tag, or if a template has none, the default branch, like main or master.

✨ CONFIG FILE ✨

The zkg command-line tool uses an INI-format config file so users can customize their Package Sources, Package installation paths, Zeek executable/source paths, and other zkg options. 🦋

See the default/example config file below for explanations of the available options and how to customize them:

# This is an example config file for zkg to explain what
# settings are possible as well as their default values.
# The order of precedence for how zkg finds/reads config files:
#
# (1) zkg --configfile=/path/to/custom/config
# (2) the ZKG_CONFIG_FILE environment variable
# (3) a config file located at $HOME/.zkg/config
# (4) if none of the above exist, then zkg uses builtin/default
#     values for all settings shown below

[sources]

# The default package source repository from which zkg fetches
# packages.  The default source may be removed, changed, or
# additional sources may be added as long as they use a unique key
# and a value that is a valid git URL.  The git URL may also use a
# suffix like "@branch-name" where "branch-name" is the name of a real
# branch to checkout (as opposed to the default branch, which is typically
# "main" or "master"). You can override the package source zkg puts
# in new config files (e.g. "zkg autoconfig")  by setting the
# ZKG_DEFAULT_SOURCE environment variable.
zeek = https://github.com/zeek/packages

[paths]

# Directory where source repositories are cloned, packages are
# installed, and other package manager state information is
# maintained.  If left blank or with --user this defaults to
# $HOME/.zkg. In Zeek-bundled installations, it defaults to
# <zeek_install_prefix>/var/lib/zkg/.
state_dir =

# The directory where package scripts are copied upon installation.
# A subdirectory named "packages" is always created within the
# specified path and the package manager will copy the directory
# specified by the "script_dir" option of each package's zkg.meta
# (or legacy bro-pkg.meta) file there.
# If left blank or with --user this defaults to <state_dir>/script_dir.
# In Zeek-bundled installations, it defaults to
# <zeek_install_prefix>/share/zeek/site.
# If you decide to change this location after having already
# installed packages, zkg will automatically relocate them
# the next time you run any zkg command.
script_dir =

# The directory where package plugins are copied upon installation.
# A subdirectory named "packages" is always created within the
# specified path and the package manager will copy the directory
# specified by the "plugin_dir" option of each package's zkg.meta
# (or legacy bro-pkg.meta) file there.
# If left blank or with --user this defaults to <state_dir>/plugin_dir.
# In Zeek-bundled installations, it defaults to
# <zeek_install_prefix>/lib/zeek/plugins.
# If you decide to change this location after having already
# installed packages, zkg will automatically relocate them
# the next time you run any zkg command.
plugin_dir =

# The directory where executables from packages are linked into upon
# installation.  If left blank or with --user this defaults to <state_dir>/bin.
# In Zeek-bundled installations, it defaults to <zeek_install_prefix>/bin.
# If you decide to change this location after having already
# installed packages, zkg will automatically relocate them
# the next time you run any zkg command.
bin_dir =

# The directory containing Zeek distribution source code.  This is only
# needed when installing packages that contain Zeek plugins that are
# not pre-built. This value is generally not needed by most users other
# than plugin developers anymore.
zeek_dist =

[templates]

# The URL of the package template repository that the "zkg create" command
# will instantiate by default.
default = https://github.com/zeek/package-template

[user_vars]

# For any key in this section that is matched for value interpolation
# in a package's zkg.meta (or legacy bro-pkg.meta) file, the corresponding
# value is substituted during execution of the package's `build_command`.
# This section is typically automatically populated with the
# the answers supplied during package installation prompts
# and, as a convenience feature, used to recall the last-used settings
# during subsequent operations (e.g. upgrades) on the same package.

👑 AUTHOR

The Zeek Project

💖 COPYRIGHT

2019, The Zeek Project

okay bestie that's the whole page, we ate and left no crumbs 💅✨ this was version 3.1.0, dated Jul 14, 2025, and it's the ZKG(1) manual page — go forth and manage your packages, main character 🫶🌸

📦 where this page comes from

ubuntu resolute: zkg 3.1.0-1 · NCSA
ubuntu stonking: zkg 3.1.0-1 · NCSA
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms