Skip to main content



Packages are a part of the Kurtosis package system. To read about the package system in detail, see here.

A Kurtosis package is a:

  • A directory
  • Plus all its contents
  • That contains a kurtosis.yml file with the package's name, which will be the locator root for the package

Kurtosis packages are the system by which Starlark scripts can include external resources.

Note that, when developing locally, a Kurtosis package's name in the kurtosis.yml can be whatever you like (the GitHub repo need not even exist).

Kurtosis packages are shared simply by pushing to GitHub (e.g. these are the packages we administer).

For example, a directory structure like so:


whose kurtosis.yml file looked like so:


would be called It should get pushed to the my-package repo owned by the me user on GitHub.

Packages are referenced indirectly, as the locators used to specify external resources in a Starlark script will contain the package name where the resource lives.

For example:

helpers = import_module("")

would be used to import the file into a Starlark script.

The Kurtosis engine will automatically download dependency packages from GitHub when running a Starlark script.

Runnable Packages

A Kurtosis package that has a file next to its kurtosis.yml file is called a "runnable package". The file of a runnable package must have a run(plan) method like so:

def run(plan):
print("Hello, world.")

More on the plan parameter here.

Runnable packages can be executed from the CLI in one of three ways:

# OPTION 1: Point to a directory with a `kurtosis.yml` and `` on local filesystem
kurtosis run /path/to/runnable/package/root
# OPTION 2: Point to a `kurtosis.yml` on the local filesystem with a `` next to it on local fileesystem
kurtosis run /path/to/runnable/package/root/kurtosis.yml
# OPTION 3: Pass in a remote package name to run from GitHub
kurtosis run

All these will call the run(plan) function of the package's


To accept parameters to the run(plan) function, the function should accept an args parameter:

def run(plan, args):
print("Hello, " +

To pass parameters to the run(plan, args) function, a JSON object should be passed as the second positional argument after the script or package path:

kurtosis run '{"name": "Joseph"}'