This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Templates

Run limactl start template://fedora to create a Lima instance named "fedora".

To open a shell, run limactl shell fedora bash or LIMA_INSTANCE=fedora lima bash.

⭐ = "Tier 1"

☆ = "Tier 2"

Default: default (⭐Ubuntu, with containerd/nerdctl)

Distro:

Alternative package managers:

Container engines:

Container image builders:

Container orchestration:

Optional feature enablers:

Lost+found:

  • centos: Removed in Lima v0.8.0, as CentOS 8 reached EOL. Replaced by almalinux, centos-stream, oraclelinux, and rocky.
  • singularity: Moved to apptainer-rootful in Lima v0.13.0, as Singularity was renamed to Apptainer.
  • experimental/apptainer: Moved to apptainer in Lima v0.13.0.
  • experimental/{almalinux,centos-stream-9,oraclelinux,rocky}-9: Moved to almalinux-9, centos-stream-9, oraclelinux-9, and rocky-9 in Lima v0.13.0.
  • nomad: Removed in Lima v0.17.1, as Nomad is no longer free software
  • centos-stream-8: Remove in Lima v0.23.0, as CentOS Stream 8 reached EOL.
  • deprecated/centos-7: Remove in Lima v0.23.0, as CentOS 7 reached EOL.
  • experimental/vz: Merged into the default template in Lima v1.0. See also <https://lima-vm.io/docs/config/vmtype/>.
  • experimental/armv7l: Merged into the default template in Lima v1.0. Use limactl create --arch=armv7l template://default.
  • experimental/riscv64: Merged into the default template in Lima v1.0. Use limactl create --arch=riscv64 template://default.
  • vmnet: Removed in Lima v1.0. Use limactl create --network=lima:shared template://default instead. See also <https://lima-vm.io/docs/config/network/>.
  • experimental/net-user-v2: Removed in Lima v1.0. Use limactl create --network=lima:user-v2 template://default instead. See also <https://lima-vm.io/docs/config/network/>.
  • experimental/9p: Removed in Lima v1.0. Use limactl create --vm-type=qemu --mount-type=9p template://default instead. See also <https://lima-vm.io/docs/config/mount/>.
  • experimental/virtiofs-linux: Removed in Lima v1.0. Use limactl create --mount-type=virtiofs-linux template://default instead. See also <https://lima-vm.io/docs/config/mount/>.

Tier

  • "Tier 1" (marked with ⭐): Good stability. Regularly tested on the CI.
  • "Tier 2" (marked with ☆): Moderate stability. Regularly tested on the CI.

Other templates are tested only occasionally and manually.

1 - GitHub template URLs

⚡ RequirementLima >= 2.0

Lima provides a special github: URL scheme to reference templates from a GitHub repo, as an alternative to using the https: scheme with a “raw” URL.

For example the templates/fedora.yaml template in the lima-vm/lima repo could be referenced as

https://raw.githubusercontent.com/lima-vm/lima/refs/heads/master/templates/fedora.yaml

Using the github: scheme this becomes:

github:lima-vm/lima/templates/fedora

⚠️ Note: github: URLs are experimental and the exact semantics may change in future releases.

General rules

File extension:

A github: URL without file extension will automatically get a .yaml suffix. So the Fedora URL above is the same as

github:lima-vm/lima/templates/fedora.yaml

File name:

The default filename for github: URLs is .lima.yaml. These URLs all reference the same file:

github:lima-vm/lima/.lima.yaml
github:lima-vm/lima/.lima
github:lima-vm/lima/
github:lima-vm/lima

Branch/tag/commit:

You can append @TAG to a github: URL to specify a branch, a tag, or a commit id. For example:

github:lima-vm/lima/templates/fedora@v2.0.0

Lima looks up the default branch of the repo when no @TAG is specified. This uses a GitHub API call.

Note: Frequent use of github: URLs may require setting GITHUB_TOKEN or GH_TOKEN to a personal access token to avoid GitHub rate limits.

Testing URL resolution

You can use the limactl template url command to see which https: URL is generated from a github: URL. For example:

❯ limactl template url github:lima-vm/lima/templates/docker
WARN[0000] The github: scheme is still EXPERIMENTAL
https://raw.githubusercontent.com/lima-vm/lima/master/templates/docker.yaml

You’ll get an error if the template does not exist:

❯ limactl template url github:lima-vm/lima
FATA[0000] file "https://raw.githubusercontent.com/lima-vm/lima/master/.lima.yaml" not found or inaccessible: status 404

Lima will check if the template file referenced by the github: URL is a symlink (or a text file whose content has no spaces, newlines, or colons). In that case it will treat the content as a relative path and return the address of that target file.

For example the fedora template is a symlink to fedora-43.yaml:

❯ limactl tmpl url github:lima-vm/lima/templates/fedora
https://raw.githubusercontent.com/lima-vm/lima/master/templates/fedora-43.yaml

Org repositories

An “org repo” has identical org and repo names (e.g. lima-vm/lima-vm). For these repos, the repo name can be omitted:

github:lima-vm/lima-vm/.lima.yaml
github:lima-vm//.lima.yaml
github:lima-vm

Org repos support two additional features that enable shorter URLs, even when the main project lives in a different repo (like lima-vm/lima instead of lima-vm/lima-vm).

Redirects:

In an org repo a template file can not only be a symlink, but also a text file containing a github: URL. The URL must point to the same GitHub org and must NOT include a @TAG. It will be used to replace the original URL.

For example assume the lima-vm projects wants to support this URL:

github:lima-vm//fedora

Then it would have to create a lima-vm/lima-vm repo with a fedora.yaml file (in the default branch) that contains:

github:lima-vm/lima/templates/fedora

Tag propagation:

Org repo redirects work with tags. For example:

github:lima-vm//fedora@v1.2.1

Lima resolves this through the following steps:

  1. Tries to load fedora.yaml from tag v1.2.1 in the lima-vm/lima-vm repo
  2. Tag doesn’t exist, so falls back to the default branch (master)
  3. Loads fedora.yaml@master, which contains the redirect: github:lima-vm/lima/templates/fedora
  4. Applies the original tag to the redirect URL

Final resolved URL:

github:lima-vm/lima/templates/fedora.yaml@v1.2.1

Lima will error if the fallback file doesn’t exist or isn’t a valid github: redirect.