Edit on GitHub

Tiltfile API Reference

class api.Blob

The result of executing a command on your local system.

Under the hood, a Blob is just a string, but we wrap it this way so Tilt knows the difference between a string meant to convey content and a string indicating, say, a filepath.

To wrap a string as a blob, call blob(my_str)

class api.CustomBuild

An image that was created with custom_build


Returns a FastBuild that is associated with the image that was built from a custom_build. When the container needs to be rebuilt it will be built using the CustomBuild. Otherwise update will be done with the FastBuild instructions.

Return type:FastBuild
class api.FastBuild

An image that was created with fast_build

add(src, dest)

Adds the content from src into the image at path dest.

  • src (str) – The path to content to be added to the image (absolute, or relative to the location of the Tiltfile).
  • dest (str) – The path in the image where the content should be added.
Return type:



Setting this on a FastBuild image tells Tilt that this container knows how to automatically reload any changes in the container. As a result there is no need to restart it.

This is useful for containers that run something like nodemon or webpack Hot Module Replacement to update running processes quickly.

Return type:None
run(cmd, trigger=[])

Runs cmd as a build step in the image.

  • cmd (str) – A shell command.
  • trigger (Union[List[str], str]) – If the trigger argument is specified, the build step is only run on changes to the given file(s).
Return type:



Creates a Blob object that wraps the provided string. Useful for passing strings in to functions that expect a Blob, e.g. k8s_yaml

Return type:Blob
api.custom_build(ref, command, deps, tag='', disable_push=False)

Provide a custom command that will build an image.

Returns an object which can be used to create a FastBuild.

It will raise an error if the specified ref is not published in the registry with the name+tag that is provided via the $EXPECTED_REF environment variable.


k8s_kind('Environment', image_json_path='{.spec.runtime.image}')
  'docker build -t $EXPECTED_REF .',
  • ref (str) – name for this image (e.g. ‘myproj/backend’ or ‘myregistry/myproj/backend’). If this image will be used in a k8s resource(s), this ref must match the spec.container.image param for that resource(s).
  • command (str) – a command that, when run in the shell, builds an image puts it in the registry as ref. Must produce an image named $EXPECTED_REF
  • deps (List[str]) – a list of files or directories to be added as dependencies to this image. Tilt will watch those files and will rebuild the image when they change.
  • tag (str) – the tag you expect the resulting image to have; we set $EXPECTED_REF=imagename:tag and use this value to verify that the command produced the correct image. (If tag is not specified, Tilt will set the expected ref to imagename:<tilt-generated temporary tag>.)
  • disable_push (bool) – whether Tilt should push the image in to the registry that the Kubernetes cluster has access to. Set this to true if your command handles pushing as well.
Return type:



Deserializes a given string from JSON to Starlark. Fails if the string can’t be parsed as JSON

Return type:Union[Dict[str, Any], List[Any]]

Specifies that any images that Tilt builds should be renamed so that they have the specified docker registry.

This is useful if, e.g., a repo is configured to push to Google Container Registry, but you want to use Elastic Container Registry instead, without having to edit a bunch of configs. For example, default_registry(“gcr.io/myrepo”) would cause docker.io/alpine to be rewritten to gcr.io/myrepo/docker.io_alpine

Parameters:registry (str) – The registry that all built images should be renamed to use.

Images are renamed following these rules: 1. Replace / and @ with _. 2. Prepend the value of registry and a /.

e.g., with default_registry(‘gcr.io/myorg’), user-service becomes gcr.io/myorg/user-service.

(Note: this logic is currently crude, on the assumption that development image names are ephemeral and unimportant. Please let us know if they don’t suit you!)

Cf. our using a personal registry guide

Return type:None
api.docker_build(ref, context, build_args={}, dockerfile='Dockerfile', dockerfile_contents='')

Builds a docker image.

Note that you can’t set both the dockerfile and dockerfile_contents arguments (will throw an error).

Example: docker_build('myregistry/myproj/backend', '/path/to/code') is roughly equivalent to the call docker build /path/to/code -t myregistry/myproj/backend

  • ref (str) – name for this image (e.g. ‘myproj/backend’ or ‘myregistry/myproj/backend’). If this image will be used in a k8s resource(s), this ref must match the spec.container.image param for that resource(s).
  • context (str) – path to use as the Docker build context.
  • build_args (Dict[str, str]) – build-time variables that are accessed like regular environment variables in the RUN instruction of the Dockerfile. See the Docker Build Arg documentation
  • dockerfile (str) – path to the Dockerfile to build
  • dockerfile_contents (Union[str, Blob]) – raw contents of the Dockerfile to use for this build
Return type:



Raises an error that cannot be intercepted. Can be used anywhere in a Tiltfile.

Return type:None
api.fast_build(img_name, dockerfile_path, entrypoint='')

Initiates a docker image build that supports add s and run s, and that uses a cache for subsequent builds.

See the fast build documentation.

Return type:FastBuild
api.filter_yaml(yaml, labels=None, name=None, namespace=None, kind=None, api_version=None)

Call this with a path to a file that contains YAML, or with a Blob of YAML. (E.g. it can be called on the output of kustomize or helm.)

Captures the YAML entities that meet the filter criteria and returns them as a blob; returns the non-matching YAML as the second return value.

For example, if you have a file of all your YAML, but only want to pass a few elements to Tilt:

# extract all YAMLs matching labels "app=foobar"
foobar_yaml, rest = filter_yaml('all.yaml', labels={'app': 'foobar'}
k8s_resource('foobar', yaml=foobar_yaml)

# extract YAMLs of kind "deployment" with metadata.name "baz"
baz_yaml, rest = filter_yaml(rest, name='baz', kind='deployment')
k8s_resource('baz', yaml=baz_yaml)
  • yaml (Union[str, List[str], Blob]) – Path(s) to YAML, or YAML as a Blob.
  • labels (Optional[dict]) – return only entities matching these labels. (Matching entities must satisfy all of the specified label constraints, though they may have additional labels as well: see the Kubernetes docs for more info.)
  • name (Optional[str]) – Case-insensitive regexp specifying the metadata.name property of entities to match
  • namespace (Optional[str]) – Case-insensitive regexp specifying the metadata.namespace property of entities to match
  • kind (Optional[str]) – Case-insensitive regexp specifying the kind of entities to match (e.g. “Service”, “Deployment”, etc.).
  • api_version (Optional[str]) – Case-insensitive regexp specifying the apiVersion for kind, (e.g., “apps/v1”)

2-element tuple containing

  • matching (Blob): blob of YAML entities matching given filters
  • rest (Blob): the rest of the YAML entities


Run helm template on a given directory that contains a chart and return the fully rendered YAML as a Blob

Parameters:pathToChartDir (str) – Path to the directory locally (absolute, or relative to the location of the Tiltfile).
Return type:Blob
api.k8s_kind(kind, api_version=None, *, image_json_path)

Tells Tilt about a k8s kind. Primarily intended for defining where your CRD specifies image names.

(Note the * in the signature means image_json_path must be passed as a keyword, e.g., image_json_path=”{.spec.image}”)


# Fission has a CRD named "Environment"
k8s_kind('Environment', image_json_path='{.spec.runtime.image}')
  • kind (str) – Case-insensitive regexp specifying he value of the kind field in the k8s object definition (e.g., “Deployment”)
  • api_version (Optional[str]) – Case-insensitive regexp specifying the apiVersion for kind, (e.g., “apps/v1”)
  • image_json_path (Union[str, List[str]]) – Either a string or a list of string containing json path(s) within that kind’s definition specifying images deployed with k8s objects of that type. This uses the k8s json path template syntax, described here.
api.k8s_resource(name, yaml='', image='', port_forwards=[], extra_pod_selectors=[])

Creates a kubernetes resource that tilt can deploy using the specified image.

  • name (str) – What call this resource in the UI. If image is not specified name will be used as the image to group by.
  • yaml (Union[str, Blob]) – Optional YAML. If this arg is not passed, we expect to be able to extract it from an existing resource (by looking for a k8s container running the specified image).
  • image (Union[str, FastBuild]) – An optional Image. If the image is not passed, we expect to be able to extract it from an existing resource.
  • port_forwards (Union[str, int, List[int]]) – Local ports to connect to the pod. If no target port is specified, will use the first container port. Example values: 9000 (connect localhost:9000 to the default container port), ‘9000:8000’ (connect localhost:9000 to the container port 8000), [‘9000:8000’, ‘9001:8001’] (connect localhost:9000 and :9001 to the container ports 8000 and 8001, respectively).
  • extra_pod_selectors (Union[Dict[str, str], List[Dict[str, str]]]) – In addition to relying on Tilt’s heuristics to automatically find K8S resources associated with this resource, a user may specify extra labelsets to force entities to be associated with this resource. An entity will be associated with this resource if it has all of the labels in at least one of the entries specified (but still also if it meets any of Tilt’s usual mechanisms).
Return type:



Call this with a path to a file that contains YAML, or with a Blob of YAML.

We will infer what (if any) of the k8s resources defined in your YAML correspond to Images defined elsewhere in your Tiltfile (matching based on the DockerImage ref and on pod selectors). Any remaining YAML is YAML that Tilt applies to your k8s cluster independently.


# path to file

# list of paths
k8s_yaml(['foo.yaml', 'bar.yaml'])

# Blob, i.e. `local` output (in this case, script output)
templated_yaml = local('./template_yaml.sh')
Parameters:yaml (Union[str, List[str], Blob]) – Path(s) to YAML, or YAML as a Blob.
Return type:None

Run kustomize on a given directory and return the resulting YAML as a Blob

Parameters:pathToDir (str) – Path to the directory locally (absolute, or relative to the location of the Tiltfile).
Return type:Blob
api.listdir(directory, recursive=False)

Returns all the files at the top level of the provided directory. If recursive is set to True, returns all files that are inside of the provided directory, recursively.

Return type:List[str]

Runs cmd, waits for it to finish, and returns its stdout as a Blob

Return type:Blob

Reads file and returns its contents.

Parameters:file_path (str) – Path to the file locally (absolute, or relative to the location of the Tiltfile).
Return type:Blob

Reads the file at path and deserializes its contents as JSON

Return type:Union[Dict[str, Any], List[Any]]