This document covers Lima's template system, including built-in templates, template variables, and custom template creation. Lima templates provide pre-configured VM configurations for common use cases and support dynamic value substitution through Go template variables.
For information about YAML processing and validation, see page 5.1. For details about configuration merging and defaults, see page 5.2.
Lima includes several built-in templates that provide pre-configured VM setups for common use cases. These templates can be referenced using the template:// scheme when creating instances.
Built-in templates are located in the templates/ directory and tested in .github/workflows/test.yml217-550 The following templates are available:
| Template Name | Description | Primary Use Case |
|---|---|---|
default | Basic Ubuntu VM with minimal configuration | General-purpose Linux VM |
docker | Ubuntu VM with Docker pre-installed | Docker container development |
k8s | Kubernetes cluster with k3s | Kubernetes development and testing |
alpine | Alpine Linux (lightweight) | Minimal footprint VM |
debian | Debian Linux | Debian-based development |
fedora | Fedora Linux | Red Hat ecosystem development |
archlinux | Arch Linux | Arch-based development |
opensuse | openSUSE Linux | SUSE-based development |
Templates can be referenced using the template:// scheme:
The template mechanism is implemented in the YAML loading process, where base: template://name references are resolved to the embedded template files.
Templates support inheritance through the base field, which can reference other templates:
Multiple levels of inheritance are supported, with later templates overriding earlier ones according to the configuration merging rules documented in page 5.2.
Sources: .github/workflows/test.yml217-550 pkg/limayaml/default.yaml1-340 hack/test-templates.sh1-700
Lima supports Go template variables in configuration values, allowing dynamic substitution based on instance metadata and user-defined parameters. Variables use the syntax {{.VariableName}} and are processed during instance creation.
Sources: pkg/limayaml/defaults.go834-852 pkg/limayaml/defaults.go854-883
Guest context variables are used in configuration fields that will be processed or used inside the VM. The executeGuestTemplate() function in pkg/limayaml/defaults.go834-852 provides these variables:
| Variable | Type | Example Value | Description |
|---|---|---|---|
{{.Name}} | string | "default" | Instance name derived from instance directory |
{{.Hostname}} | string | "lima-default" | VM hostname generated by hostname.FromInstName() |
{{.UID}} | uint32 | 501 | Guest user ID from the user configuration |
{{.User}} | string | "alice" | Guest username from the user configuration |
{{.Home}} | string | "/home/alice.linux" | Guest home directory path |
{{.Param.KEY}} | string | User-defined | Custom parameter value from param map |
Host context variables are used in configuration fields that reference host system paths and resources. The executeHostTemplate() function in pkg/limayaml/defaults.go854-883 provides these variables:
| Variable | Type | Example Value | Description |
|---|---|---|---|
{{.Dir}} | string | "/Users/alice/.lima/default" | Full path to instance directory |
{{.Name}} | string | "default" | Instance name |
{{.UID}} | string | "501" | Host user ID |
{{.User}} | string | "alice" | Host username |
{{.Home}} | string | "/Users/alice" | Host home directory |
{{.Param.KEY}} | string | User-defined | Custom parameter value from param map |
{{.GlobalTempDir}} | string | "/tmp" (Unix)C:\Temp (Windows) | System-wide temporary directory |
{{.TempDir}} | string | OS-specific | User-specific temporary directory |
{{.Instance}} | string | "default" | DEPRECATED: Use {{.Name}} |
{{.LimaHome}} | string | "/Users/alice/.lima" | DEPRECATED: Use {{.Dir}} |
Sources: pkg/limayaml/defaults.go834-852 pkg/limayaml/defaults.go854-883
Template variables can be used in specific configuration fields. The processing occurs during the FillDefault() function in pkg/limayaml/defaults.go138-794:
| Field | Context | Example Usage |
|---|---|---|
user.home | Guest | "/home/{{.User}}.linux" |
provision[].script | Guest | "#!/bin/bash\necho {{.User}}" |
provision[].content | Guest | "User: {{.User}}\nUID: {{.UID}}" |
provision[].expression | Guest | ".version = \"{{.Param.VERSION}}\"" |
provision[].owner | Guest | "{{.User}}:{{.User}}" |
provision[].path | Guest | "/home/{{.User}}/config" |
probes[].script | Guest | "#!/bin/sh\ntest -f {{.Home}}/ready" |
mounts[].location | Host | "{{.Home}}/projects" |
mounts[].mountPoint | Guest | "/mnt/{{.Param.PROJECT}}" |
portForwards[].guestSocket | Guest | "/run/user/{{.UID}}/socket" |
portForwards[].hostSocket | Host | "{{.Dir}}/sock/socket" |
copyToHost[].guestFile | Guest | "{{.Home}}/output.log" |
copyToHost[].hostFile | Host | "{{.Home}}/lima-logs/output.log" |
Template processing happens after configuration merging but before validation, allowing inherited templates to use variables that will be resolved at instance creation time.
Sources: pkg/limayaml/defaults.go199-203 pkg/limayaml/defaults.go398-451 pkg/limayaml/defaults.go521-526 pkg/limayaml/defaults.go640-668 pkg/limayaml/defaults.go913-924 pkg/limayaml/defaults.go939-953
The param map allows defining custom variables that can be referenced throughout the configuration:
Parameter names must start with a letter and contain only letters, digits, and underscores, as validated in pkg/limayaml/validate.go396-408 Parameters are available as environment variables $PARAM_KEY in provision scripts and probes.
The user home directory supports template variables for dynamic paths:
This is processed in pkg/limayaml/defaults.go199-203 and allows customizing the guest home directory based on the username or other variables.
Provision scripts can use template variables for dynamic configuration:
Mounts can use different template contexts for host and guest paths:
The location field uses host variables (like {{.Home}} referring to the host home directory), while mountPoint uses guest variables.
Socket forwarding paths can be customized using template variables:
This example forwards the Docker socket from the guest to a socket file in the instance directory on the host.
Sources: pkg/limayaml/defaults.go199-203 pkg/limayaml/defaults.go398-451 pkg/limayaml/defaults.go640-668 pkg/limayaml/defaults.go913-924 pkg/limayaml/validate.go396-408 hack/test-templates/test-misc.yaml16-113
Custom templates are YAML files that follow the Lima configuration schema documented in pkg/limayaml/default.yaml Templates can inherit from other templates using the base field:
The configuration merging follows the priority order documented in page 5.2. Template variables are resolved after all configurations are merged but before validation.
Sources: pkg/limayaml/load.go23-75 pkg/limayaml/defaults.go138-794
This example creates a template for web development with Node.js and Docker:
Custom templates can be validated before use:
The validation process is implemented in pkg/limayaml/validate.go34-421 and checks all configuration fields including template variable syntax.
Sources: pkg/limayaml/default.yaml1-340 pkg/limayaml/validate.go34-421 hack/test-templates/test-misc.yaml1-124
When template variable processing fails, Lima logs a warning but continues with the original untemplated value. This graceful degradation allows instances to start even with malformed templates.
Template variable processing in pkg/limayaml/defaults.go199-203 follows this pattern:
Common error scenarios:
The error is logged but doesn't prevent instance creation, with the original value used unchanged.
Sources: pkg/limayaml/defaults.go199-203 pkg/limayaml/defaults.go398-451 pkg/limayaml/defaults.go640-668
Lima implements sophisticated list combination logic for additionalDisks, mounts, and networks that allows entries to be merged based on shared keys and wildcard patterns.
The combineListEntries() function in pkg/limatmpl/embed.go331-548 implements sophisticated merging logic for three list types:
For additionalDisks with wildcard entries:
Sources: pkg/limatmpl/embed.go331-548 pkg/limatmpl/embed_test.go252-278
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.