Skip to main content



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

A locator is how resources are identified when being imported in a Starlark script - namely by import_module and read_file. There are two types of locators: absolute and relative.

Absolute Locators

Absolute locators unambiguously identify a resource using a URL-like syntax. For example, this locator:

references a file inside a GitHub repo called package-repo, owned by package-author, that lives at the path /path/to/directory-with-kurtosis.yml/ relative to the root of the repo.


A GitHub URL is not a valid locator, because GitHub adds extra /blob/main paths to the URL that don't reflect the file's path in the repo. For example, a GitHub URL of:

would be the following as a Kurtosis locator (dropping the https:// and /blob/main part):

Only locators pointing to public GitHub repositories are currently allowed.

Important Package Restriction

If your Starlark script relies on local resources, such as files or packages available on your filesystem, then those resources must be part of a Kurtosis package.

For example, suppose we had a Kurtosis package like so:


with a kurtosis.yml file like so:


In your file, you would be able to import the from the helpers subdirectory of my-package like so:

# Valid
helpers = import_module("")

However, if you try to import package-repo/not-a-package/, then it will not work because package-repo/not-a-package/ is not part of a package. In essence, the import statement below will not succeed, because cannot import from non-packages (see how import works for more information):

# Invalid
helpers = import_module("")

Relative Locators

Relative locators like ./ are allowed as a short alternative to the full absolute locator. However, a relative locator cannot be used to reference files outside the package. In other words, you cannot use a relative locator to reference files above the directory containing the kurtosis.yml file.

Suppose we had a Kurtosis package like so:


with a kurtosis.yml file like so:


The can refer to the file using either relative or absolute imports:

# valid relative import
lib_via_relative_import = import_module("./src/")

# valid absolute import
lib_via_absolute_import = import_module("")