Dependencies & Supported Package Managers

Zoi can install dependencies via many ecosystem and OS package managers. This page documents:

• How to declare dependencies in .pkg.lua
• All supported managers, their target platforms/ecosystems, and example usage
• Notes and caveats for specific managers

Declaring dependencies in .pkg.lua

Dependencies are specified in the dependencies section. Both runtime and build dependency groups can be defined as a simple list of required dependencies, or as a more advanced object with required, optional, and selectable options.

Dependency String Format

Each entry follows the format: manager:package[:sub-package] with an optional version and an optional inline description.

• Format: manager:package[:sub-package][@version][:description]
• Virtual Packages: You can depend on a virtual package name that is satisfied by any package that includes it in its provides list.
• Sub-packages: For zoi packages that are split, you can specify a sub-package.
  • Example: zoi:linux:headers
• Version: Can be specified with @<semver> or a comparator string like =1.2.3, >=2.0.0, ^1.2, ~1.2.3. Do not prefix with v.
  • Examples: npm:[email protected], cargo:[email protected], apt:curl=7.68.0-1ubuntu2.18.
  • For zoi packages, you can use a channel name like zoi:my-pkg@stable.
• Description: An inline description can be added after the last colon. It must not contain version characters.
  • Example: pipx:black:Python formatter CLI.
• Native Packages: Use native:<pkg> to have Zoi automatically select the system's package manager.

Simple Dependency List

For packages with only required dependencies, you can use a simple list of strings.

dependencies({
  runtime = { "native:openssl", "npm:typescript", "zoi:some-zoi-package" },
  build = { "native:make" }
})

Advanced Dependency Object

For more complex scenarios involving optional or selectable dependencies, use nested tables.

dependencies({
  runtime = {
    required = { "zoi:core-utils" },
    options = {
      {
        name = "GUI Toolkit",
        desc = "Choose a GUI provider for the application",
        all = false, -- false means the user must choose one. true allows multiple selections.
        depends = {
          "native:qt6:Recommended for KDE Plasma",
          "native:gtk4:Recommended for GNOME"
        }
      }
    },
    optional = { "zoi:extra-utils:handy extras" },
    -- Per-sub-package dependencies
    sub_packages = {
      kernel = {
        required = { "zoi:linux-firmware" }
      },
      headers = {
        required = { "native:pahole" }
      }
    }
  },
  build = {
    -- Build dependencies can be general (for all build types)
    -- or specific to a build type using the 'types' table.
  }
})

-- Example of general build dependencies
dependencies({
  build = {
    required = { "native:cmake" }
  }
})

-- Example of build-type-specific dependencies
dependencies({
  build = {
    types = {
      source = {
        required = { "native:gcc", "native:make" }
      },
      ["pre-compiled"] = {
        optional = { "native:unzip" }
      }
    }
  }
})

• required: A list of dependencies that are always installed.
• options: A list of groups where the user is prompted to choose one or more dependencies.
• optional: A list of dependencies that the user is prompted to install.
• sub_packages: A table where keys are sub-package names and values are dependency groups (required, options, optional). These dependencies are only installed for the specified sub-package.

Dynamic Versions with Lua

In .pkg.lua files, you can use Lua's string concatenation and the global PKG table to create dynamic version dependencies. The PKG table contains the fields defined in your package{} block.

Example with dynamic versions:

package({
  name = "my-app",
  versions = {
    stable = "1.4.3",
    beta = "1.5.0-beta.2"
  }
  -- Zoi will resolve the default version (e.g. from the 'stable' channel)
  -- and place it in PKG.version before processing dependencies.
})

dependencies({
  runtime = {
    required = {
      "zoi:my-plugin@" .. PKG.version,
      "npm:my-lib@" .. PKG.version
    }
  }
})

Version Pinning Notes

Zoi parses version specifiers using standard SemVer requirements (e.g. >1.2.3, ~2.4, ^3). However, the ability to enforce these versions depends on the underlying package manager.

When pinning is not supported, Zoi will install the latest version available from the package manager and may print a warning.

Supported managers

Below is a comprehensive list of all supported dependency managers, their target platforms or ecosystems, and an example of how to use them in your .pkg.lua.

Notes:

• AUR: aur:<pkg> builds from source using makepkg; uninstall is done with pacman.
• native:<pkg> selects the appropriate system manager based on OS/distro; if none can be detected, Zoi errors.
• Some managers (e.g. go, jsr, volta, uv) do not provide reliable uninstall; Zoi prints a notice and skips.
• Deno: deno:npm-chalk or deno:jsr-@std/bytes (the - instead of : is important).

Zoi Dependencies and Conflict Checks

When a dependency uses the zoi: manager, Zoi resolves the referenced package definition and applies the same conflict checks as for a top-level install:

• If the dependency package declares bins, Zoi checks whether any of those binaries are already provided by installed packages.
• If the dependency package declares conflicts, Zoi checks whether any listed packages are installed.

If conflicts are detected, Zoi displays the conflicts and prompts whether to continue before proceeding with installation.

Troubleshooting

• Some managers require being present on PATH. Run zoi info to see which managers Zoi detects.
• On macOS, GUI apps use brew-cask; App Store apps require mas to be signed in.
• On Arch-based systems, you can choose between helpers (yay, paru, pikaur, trizen) or use aur: to build with makepkg.