Skip to main content
Version: 0.77.1



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, the GitHub repo referred to in the package name does not need to exist.

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

For example, suppose there is a repo called package-repo by the author package-author whose internal directory structure looks like so:


whose kurtosis.yml file looked like so:


The package would be called It should get pushed to the package-repo repo owned by the package-author 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

If you want to run a non-main branch, tag or commit use the following syntax kurtosis run[email protected]

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


Kurtosis packages can be parameterized with arguments by adding an args parameter to the run function. Read more about package arguments here.