Skip to content

PackageDependency

A PackageDependency declares a package or module that must be present before a component starts. Dependencies are listed in manifest.yaml as compact requirement strings:

name: my-app
version: 1.0.0
dependencies:
  - myutils>=1.0.0
  - modb==2.0.0
  - analytics

The general format is:

name[version specifier]
Part Description
name Name of the package or module.
version specifier Optional. One of ==, >=, <=, >, <, ~= followed by a version. Defaults to latest available.

Add a dependency from the CLI:

kxi package add --to my-app dep --name myutils --version 1.0.0

How dependencies are resolved

When a package is deployed, each DAP, Aggregator, Stream Processor, and KDB-X Workload runs a sidecar init container (kxi-kdbx-init) that resolves, downloads, and makes available the declared dependencies before the main process starts. Packages are automatically accessible via use in q or import in Python — no manual loading required in most cases.

KXI_PACKAGES

Under the hood, dependency resolution populates KXI_PACKAGES (the list of packages and modules to download on startup) and KXI_PACKAGE_ENTRYPOINTS (the entrypoints to load). Prefer declaring dependencies over setting KXI_PACKAGES manually. The main exception is the Global Aggregator (global_agg), which kdb Insights Package Manager does not manage. Refer to Load multiple packages into a DAP for details.

Package index resolution strategy

The init container uses UV_INDEX_STRATEGY=first-index when installing Python packages. Indexes are resolved per package name:

  1. The kdb Insights Package Manager index is consulted first.
  2. If the package name is found in the kdb Insights Package Manager index, only the kdb Insights Package Manager is used to resolve that package — uv does not check PyPI for a different version, even if the requested version is not available in the kdb Insights Package Manager index.
  3. If the package name is not found on the kdb Insights Package Manager at all, uv falls back to PyPI (provided your environment permits external internet access).

This behavior is intentional for a trusted kdb Insights Package Manager setup:

  • Air-gapped compatibility — installs work whether or not the cluster can reach PyPI. Any package on the kdb Insights Package Manager is resolvable without external access.
  • Dependency-confusion protection — a public PyPI release cannot shadow an internal package by advertising a higher version. Once the kdb Insights Package Manager claims a package name, PyPI is never consulted for it.

Version not found on kdb Insights Package Manager

If a specific version of a package is required and that version exists only on PyPI, the install will fail even if an older version of the same package is on the kdb Insights Package Manager. Push the required version to the kdb Insights Package Manager first with kxi pm push.

Transitive dependencies

Dependencies are resolved transitively. If moda depends on modb, and modb depends on modc, all three are downloaded and made available when a service uses moda.

# modc/manifest.yaml
name: modc
version: 1.0.0

# modb/manifest.yaml
name: modb
version: 1.0.0
dependencies:
  - modc

# moda/manifest.yaml
name: moda
version: 1.0.0
dependencies:
  - modb

Push all packages to the kdb Insights Package Manager before deploying any component that uses them:

kxi pm push modc/
kxi pm push modb/
kxi pm push moda/

Any service that declares moda as a dependency will have modb and modc downloaded and made available on startup.

Contexts

Context Relationship Object Path Package File Path
Package.dependencies Package -> PackageDependency $.dependencies[*] {package-root}/manifest.yaml
Manifest.dependencies Package -> Manifest -> PackageDependency $.manifest.dependencies[*] {package-root}/manifest.yaml

Fields

This schema does not declare object fields.

No linked schemas.

Used In

Back to top