limactl

Manage Linux virtual machines on macOS

TLDR

List VMs

$ limactl list

Create a VM using the default settings and optionally provide a name and/or a template (see limactl create --list-templates for available templates)

$ limactl create --name [vm_name] template://[debian|fedora|ubuntu|...]

Start a VM (this might install some dependencies in it and take a few minutes)

$ limactl start [vm_name]

Open a remote shell inside a VM

$ limactl shell [vm_name]

Run a command inside a VM

$ limactl shell [vm_name] [command]

Stop/shutdown a VM

$ limactl stop [vm_name]

Delete a VM

$ limactl remove [vm_name]

SYNOPSIS

limactl [global_options] command [command_options] [arguments]

create [file]
    Creates a new Lima instance based on a specified YAML configuration file. If no file is provided, it uses a default template.

start [name]
    Starts an existing Lima instance. If name is omitted, it attempts to start the default instance or prompts for selection.

stop [name]
    Stops a running Lima instance. If name is omitted, it attempts to stop the default instance.

shell [name] [command ...]
    Opens an interactive shell (e.g., bash) inside a Lima instance or executes a specific command within it.

list
    Lists all Lima instances, showing their status, SSH address, and other relevant information.

delete [name]
    Deletes a Lima instance and all its associated data, including its virtual disk image.

edit [name]
    Opens the YAML configuration file for a specified Lima instance in your default editor for modification.

install [name]
    Installs or updates guest agents and other necessary components within a Lima instance for optimal performance and integration.

prune
    Removes stale Lima artifacts such as cached virtual machine images and temporary files to free up disk space.

validate file
    Validates the syntax and structure of a Lima instance YAML configuration file without attempting to create an instance.

factory-reset
    Resets Lima to its initial state, deleting all instances and associated data. This action is irreversible.

--debug
    Enables verbose debug logging, providing detailed output for troubleshooting purposes.

--log-level level
    Sets the logging verbosity level for limactl output (e.g., info, warn, error, debug).

--version
    Displays the limactl version information and exits.

DESCRIPTION

limactl is the command-line interface for Lima (Linux-on-Mac), a lightweight system for running Linux virtual machines on macOS and Linux hosts. It simplifies the process of setting up and managing Linux environments, often used for container development (e.g., Docker, containerd, Kubernetes) and other Linux-dependent workflows.

limactl allows users to create, start, stop, delete, and shell into Linux instances, as well as manage their configurations, port forwarding, and shared file systems. It provides a seamless way to run Linux applications and tools natively on your host operating system, acting as a convenient bridge for development.

CAVEATS

Lima primarily targets macOS and Linux hosts; official support for Windows is typically via WSL2 integration, which might differ in behavior. It relies on a hypervisor (e.g., QEMU) being available on the host system. Instance configuration is managed via YAML files, which requires familiarity with the format. Performance can vary based on host hardware and allocated VM resources.

CONFIGURATION FILES

Lima instances are defined by YAML configuration files. These files allow users to specify detailed settings such as the Linux distribution to use, CPU and memory allocation, disk size, port forwarding rules, and host-guest shared directory mounts. This highly configurable nature makes Lima adaptable to various development workflows.

CONTAINER RUNTIME INTEGRATION

Many Lima instance templates come pre-configured with containerd and its CLI client, nerdctl. This allows users to seamlessly build, run, and manage OCI-compliant containers within their Lima VMs, often serving as a full-fledged container development environment without the need for separate Docker Desktop installations.

HISTORY

Lima was created by Akihiro Suda, with its initial public releases occurring around late 2020 and early 2021. It quickly gained traction as a lightweight and open-source alternative to proprietary solutions like Docker Desktop for running Linux environments on macOS. Its design emphasizes simplicity, tight integration with container runtimes like containerd and nerdctl, and ease of use for developers.