Lima 使用文档

Lima（Linux Machines）是在 macOS、Linux 等宿主机上创建 Linux 虚拟机的轻量工具。它常用来在 Mac 上获得接近原生 Linux 的开发环境，并内置文件共享、端口转发、containerd/nerdctl 等能力。

适合场景：

• 在 macOS 上跑 Linux 命令、服务端程序、CI 脚本
• 需要隔离的开发环境
• 不想安装完整 Docker Desktop，但想跑容器
• 需要多套不同发行版或不同资源规格的虚拟机

安装

macOS 推荐用 Homebrew：

brew install lima

其他安装方式：

# MacPorts
sudo port install lima

# Nix
nix-env -i lima

如果使用 QEMU 作为虚拟化驱动，需要系统中有 QEMU；在 macOS 上 Lima 也可以使用 Apple 的 Virtualization.framework（配置中通常写作 vz）。

安装后检查：

limactl --version
limactl --help

最快创建一个虚拟机

创建并启动默认实例：

limactl start

第一次执行时，Lima 会弹出交互式选择。一般选择：

Proceed with the current configuration

看到 READY 后，进入默认虚拟机：

lima

在默认虚拟机里执行一条命令：

lima uname -a
lima cat /etc/os-release

退出虚拟机 shell：

exit

非交互创建适合脚本：

limactl start --tty=false

# 或者使用 -y，含义相同
limactl start -y

创建具名虚拟机

日常更推荐给虚拟机取名字，方便同时管理多台实例。

# 使用默认模板创建 dev
limactl start --name dev template:default

# 使用 Ubuntu LTS 模板创建 ubuntu
limactl start --name ubuntu template:ubuntu-lts

# 创建 Debian
limactl start --name debian template:debian

进入具名实例：

limactl shell dev

在具名实例里执行命令：

limactl shell dev uname -a
limactl shell dev -- sudo apt update

也可以让 lima 快捷命令临时指向某个实例：

LIMA_INSTANCE=dev lima uname -a

生命周期管理

# 查看实例
limactl list

# 启动已经存在的实例
limactl start dev

# 停止实例
limactl stop dev

# 重启实例
limactl restart dev

# 删除实例，删除前最好确认没有重要数据只放在虚拟机磁盘里
limactl delete dev

# 非交互删除
limactl delete dev -f

查看实例目录：

limactl list dev --format '{{.Dir}}'

实例通常位于：

~/.lima/<实例名>/

按资源规格创建虚拟机

创建时指定 CPU、内存、磁盘：

limactl start --name dev \
  --cpus 4 \
  --memory 8 \
  --disk 80 \
  template:ubuntu-lts

说明：

• --cpus 4：分配 4 个 CPU
• --memory 8：分配 8 GiB 内存
• --disk 80：分配 80 GiB 磁盘
• 这些创建期参数一般应在实例创建时确定；已创建实例要改配置，通常需要停机后编辑

停机后编辑实例配置：

limactl stop dev
limactl edit dev
limactl start dev

使用模板

列出内置模板：

limactl start --list-templates

常用模板：

limactl start --name ubuntu template:ubuntu-lts
limactl start --name debian template:debian
limactl start --name fedora template:fedora
limactl start --name arch template:archlinux
limactl start --name docker template:docker
limactl start --name podman template:podman
limactl start --name k3s template:k3s
limactl start --name k8s template:k8s

如果想把创建和启动拆开：

limactl create --name dev template:ubuntu-lts
limactl start dev

自定义 YAML 创建虚拟机

创建 dev.yaml：

minimumLimaVersion: "2.0.0"

base:
  - template:ubuntu-lts

cpus: 4
memory: "8GiB"
disk: "80GiB"

mountType: "virtiofs"
mounts:
  - location: "~"
    writable: false
  - location: "~/projects"
    mountPoint: "/workspace"
    writable: true

portForwards:
  - guestPort: 8080
    hostPort: 8080
  - guestPort: 3000
    hostPort: 3000

provision:
  - mode: system
    script: |
      #!/bin/bash
      set -euxo pipefail
      apt-get update
      apt-get install -y git curl build-essential

用 YAML 创建并启动：

limactl start --name dev ./dev.yaml

进入验证：

limactl shell dev
ls /workspace

文件共享

默认模板会把宿主机 home 目录以只读方式挂载进虚拟机。macOS 宿主机里路径通常保持为：

/Users/<你的用户名>

虚拟机自己的 home 目录是独立的。Lima 2.1 之后，Linux guest 通常使用：

/home/<你的用户名>.guest

临时让默认挂载可写：

limactl start --name dev --mount-writable template:default

创建时指定挂载：

limactl start --name dev \
  --mount ~/projects:w \
  template:ubuntu-lts

YAML 中指定挂载：

mounts:
  - location: "~/projects"
    mountPoint: "/workspace"
    writable: true

常见挂载类型：

创建时指定挂载类型：

limactl start --name dev --vm-type=vz --mount-type=virtiofs template:ubuntu-lts
limactl start --name dev-qemu --vm-type=qemu --mount-type=9p template:ubuntu-lts

复制文件

不想配置共享目录时，可以直接复制文件：

# 宿主机 -> 虚拟机
limactl copy ./local-file.txt dev:/tmp/

# 虚拟机 -> 宿主机
limactl copy dev:/tmp/result.txt ./

端口转发

Lima 支持把虚拟机内监听的 localhost 端口转发到宿主机。

例如在虚拟机里启动服务：

limactl shell dev -- python3 -m http.server 8080

宿主机访问：

curl http://127.0.0.1:8080

创建时通过命令行指定端口：

limactl start --name web --port-forward 8080:80 template:ubuntu-lts

YAML 中指定端口：

portForwards:
  - guestPort: 80
    hostPort: 8080
  - guestPort: 3000
    hostPort: 3000

忽略某个端口：

portForwards:
  - guestPort: 22
    ignore: true

如果要通过虚拟机 IP 访问，而不是只通过 localhost，可以给实例连接 vzNAT 或 lima:shared 网络：

limactl start --name dev --network vzNAT template:ubuntu-lts
limactl shell dev -- ip addr show lima0

虚拟化驱动

常用驱动：

创建 VZ 实例：

limactl start --name dev --vm-type=vz template:ubuntu-lts

在 Apple Silicon Mac 上启用 Rosetta：

limactl start --name dev \
  --vm-type=vz \
  --rosetta \
  template:ubuntu-lts

对应 YAML：

vmType: "vz"
rosetta:
  enabled: true
  binfmt: true

使用 containerd 和 nerdctl

Lima 默认集成 containerd，可用 nerdctl 运行容器。用法和 Docker CLI 很像。

# 在默认实例里运行 nginx
lima nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine

# 查看容器
lima nerdctl ps

# 停止并删除
lima nerdctl rm -f nginx

具名实例：

limactl shell dev -- nerdctl ps

创建时禁用 containerd：

limactl start --name plain --containerd=none template:ubuntu-lts

使用 rootful containerd：

limactl start --name ctr --containerd=system template:ubuntu-lts
limactl shell ctr -- sudo nerdctl ps

使用 Docker

如果要使用 Docker Engine，可以直接使用 Docker 模板。

Rootless Docker：

limactl start template:docker
export DOCKER_HOST="$(limactl list docker --format 'unix://{{.Dir}}/sock/docker.sock')"
docker run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
docker ps

Rootful Docker：

limactl start template:docker-rootful
export DOCKER_HOST="$(limactl list docker-rootful --format 'unix://{{.Dir}}/sock/docker.sock')"
docker run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
docker ps

也可以把 DOCKER_HOST 写入 shell 配置：

echo 'export DOCKER_HOST="$(limactl list docker --format '\''unix://{{.Dir}}/sock/docker.sock'\'')"' >> ~/.zshrc

SSH 连接

查看 SSH 命令：

limactl show-ssh dev

直接 SSH：

ssh -F ~/.lima/dev/ssh.config lima-dev

在脚本中更推荐用：

limactl shell dev -- command args

快照

快照适合在大改系统前留回滚点。

limactl snapshot create dev --tag before-upgrade
limactl snapshot list dev
limactl snapshot apply dev --tag before-upgrade
limactl snapshot delete dev --tag before-upgrade

全局默认配置

可以在以下位置放全局默认配置：

~/.lima/_config/default.yaml

例如让新实例默认使用 VZ 和 virtiofs：

vmType: "vz"
mountType: "virtiofs"

还有一个覆盖配置：

~/.lima/_config/override.yaml

override.yaml 会覆盖具体实例的配置，适合强制应用某些全局策略。谨慎使用。

常见问题

端口访问不到

检查服务是否在虚拟机内监听：

limactl shell dev -- ss -ltnp

如果服务只监听虚拟机内某个非 localhost 地址，先改成监听 0.0.0.0 或 127.0.0.1 再测试。

共享目录不可写

默认 home 挂载通常是只读的。创建实例时用：

limactl start --name dev --mount ~/projects:w template:ubuntu-lts

或在 YAML 里设置：

mounts:
  - location: "~/projects"
    writable: true

改了 YAML 但没生效

部分配置是创建期配置，不能对已存在实例直接变更。稳妥做法：

limactl stop dev
limactl edit dev
limactl start dev

如果仍无效，可能需要删除重建：

limactl delete dev
limactl start --name dev ./dev.yaml

磁盘空间不够

查看磁盘：

limactl disk list

调整磁盘需参考当前版本的 limactl disk resize 帮助：

limactl disk resize --help

推荐日常流程

# 1. 创建开发 VM
limactl start --name dev --cpus 4 --memory 8 --disk 80 template:ubuntu-lts

# 2. 进入 VM
limactl shell dev

# 3. 在 VM 中安装依赖
sudo apt update
sudo apt install -y git curl build-essential

# 4. 宿主机执行 VM 命令
limactl shell dev -- uname -a

# 5. 停止 VM
limactl stop dev

# 6. 再次启动
limactl start dev

参考链接

• Lima 官方文档
• Installation
• Usage
• limactl start
• Templates
• Filesystem mounts
• Port Forwarding
• containerd
• Docker