kurtosis.yml is part of the Kurtosis package system. To read about the package system in detail, see here.
kurtosis.yml file is a manifest file necessary to turn a directory into a Kurtosis package. This is the spec for the
# The locator naming this package.
# The package's description which will be shown in the Enclave Manager on the UI.
description: A sentence describing what the package does
# The package's dependencies replace options
# Replacing the official Postgres package with my fork
if kurtosis.yml is in the repository root:
if kurtosis.yml is in a directory other than repository root:
The key take away is that
/path/to/directory-with-kurtosis.yml only needs to be provided if
kurtosis.yml is not present in the repository's root.
There are often times when you want to substitute one of your Kurtosis package’s dependencies with another dependency. For example, someone might have forked one of your package's dependencies, and you want to test your package against their fork rather than the normal version. Finding and updating all the dependency-referencing commands (
read_file, etc.) in your package is tedious and error-prone, so the
kurtosis.yml supports a
replace key to do it for you.
replace key accepts a key-value map where each key is the locator of a package to be replaced, and each value is the package locator to replace it with.
# Replacing the official Postgres package with my fork
This behaves just as if you’d manually updated each Starlark dependency-referencing command that consumes
github.com/kurtosis-tech/postgres-package and replaced it with
github.com/my-github-user/postgres-package. This replace includes transitive dependencies: a dependency package that itself uses
github.com/kurtosis-tech/postgres-package will also instead now use
replace entry does nothing if replaced package isn't actually depended upon.
You may optionally append an
@ and version after the replacement package locator to specify which version of the replacement package ought to be used.
# Replacing the official Postgres package with version 1.2.3
github.com/kurtosis-tech/postgres-package: github.com/my-github-user/postgres-[email protected]
import_module and all other dependency-referencing commands, the version can be a tag, branch, or a full commit hash.
Go programmers will identify the similarities with the
replace directive in the
go.mod file. This is not accidental; the Kurtosis packaging system draws heavy inspiration from the Go module system.
Replace In kurtosis.yml Of Dependencies
replace instructions are only evaluated in the
kurtosis.yml of the root package being called, and are ignored in the
kurtosis.ymls of package dependencies.
For example, suppose we had two packages, Dependency and Consumer
, that both use github.com/kurtosis-tech/postgres-package
in their Starlark.
Additionally, Consumer depends on Dependency in its Starlark code.
Theirkurtosis.yml` files look like so:
# NOTE: this package uses github.com/kurtosis-tech/postgres-package in its Starlark
# Replace the official Postgres package with the fork from user 'someboday'
# NOTE: this package uses both of these in its Starlark:
# - github.com/somebody/dependency
# - github.com/kurtosis-tech/postgres-package
# This package does NOT have a 'replace' directive
If the user runs Consumer (
kurtosis run github.com/somebody/consumer), Dependency's
replace will not be evaluated. This is because
replace instructions are only executed in the
kurtosis.yml of the root package.
You might need to replace one of your package's GitHub dependencies with a local version on your filesystem. For example, suppose you're developing on one of your package's dependencies. When doing so, updating all the dependency-referencing commands like
import_module would be painful. To support this use case, the value of a
replace line can be an absolute or relative path on your local filesystem to a Kurtosis package (a directory containing a
# Replace the official Postgres package with the version on my filesystem (relative import)
# Replace the official MongoDB package with the version on my filesystem (absolute import)
Kurtosis identifies a local package filepath whenever the replacement package locator begins with
.. If the filepath does not point to a directory containing a
kurtosis.yml file, an error will be thrown. When local filepath locators are used, any
@ in the value will be treated as part of the filepath (rather than indicating a version).
Colliding Replace Values
It is possible to have two Kurtosis packages, one nested within the other.
For example, suppose we have
To the Kurtosis packaging system, these packages do not have any hierarchical relation and are simply treated as two entirely separate packages with different identifiers for dependency purposes.
However, this still presents a problem for
replace: let's suppose you have your own package that depends on both
child, and you want to
How does this work?
When one package exists in a subpath of another, the more specific (child) package gets replaced first. For example, if your package's
kurtosis.yml looks like so...
# Replace parent with new-parent
# Replace child with new-child
...and you have Starlark code inside your package that looks like this...
child = import_module("github.com/kurtosis-tech/parent/child/main.star")
...then Kurtosis would use the "more specific" rule to replace
import_module call would then be functionally equivalent to the following:
child = import_module("github.com/mieubrisse/new-child/main.star")
In other words, replace directives are matched “longest match first”.