From Vagrant to Lima: How Trellis Modernized WordPress Local Development

Emnes April 17, 2026

Illustration showing migration from Vagrant to Lima VMs for local WordPress development

For over a decade, Vagrant was the default local development tool for any serious WordPress developer. It worked on macOS, Linux, and Windows. It let you run a full Linux VM with nginx, PHP, MariaDB, and everything else your production server had. It was the beating heart of Trellis-based workflows. And in October 2025, the Roots.io team dropped Vagrant support entirely and replaced it with Lima VMs.

The switch was the biggest change to Trellis since its initial release. For existing Trellis users, it meant learning a new local dev tool. For new users, it meant a dramatically faster and more reliable starting experience. This post covers what changed, why the switch happened, how to migrate an existing Trellis project from Vagrant to Lima, and what the day-to-day Lima workflow looks like for WordPress development.

Why Roots Moved Away from Vagrant

Vagrant, launched in 2010, pioneered the “development VMs as code” pattern. Its great achievement was abstracting over different virtualization backends (VirtualBox, VMware, Parallels, Hyper-V) so you could write one Vagrantfile and it worked on any developer’s machine.

But by 2025, that abstraction was a liability:

VirtualBox never worked well on Apple Silicon. M1/M2/M3/M4 Macs needed Oracle’s preview builds, which had been “experimental” for years. Parallels worked but cost $100/year per developer.
Ruby dependency. Vagrant was a Ruby application, which meant every developer needed a compatible Ruby runtime, which was fine in 2015 and increasingly annoying in 2025 as Ruby versions drifted.
NFS file sync was slow. Large WordPress projects with thousands of media files suffered painful sync delays. Alternatives (rsync, SMB) had their own problems.
HashiCorp changed their licensing. Vagrant moved to the Business Source License (BSL) in 2023, creating uncertainty about long-term open-source status.
Bootstrap time was slow. A fresh vagrant up could take 3–5 minutes on a reasonable machine.

The Roots team published the rationale in detail in their Trellis Drops Vagrant in Favor of Lima blog post (October 2025).

What Is Lima?

Lima (short for “Linux Machines”) is an open-source virtual machine manager originally built for running Docker-alternative Linux containers on macOS. It’s written in Go, uses native virtualization frameworks, and has become the backbone of several popular developer tools (Rancher Desktop, Colima).

On macOS, Lima uses Virtualization.framework — Apple’s native hypervisor — with no VirtualBox-style translation layer. On Linux, it uses KVM. The result: near-native VM performance with minimal overhead.

For Trellis, Lima provides:

Native virtualization — no Ruby, no VirtualBox, no licensed hypervisor.
Much faster boot — 30–60 seconds cold, near-instant resume.
Better file sync — Lima’s VirtioFS mount is faster and more reliable than Vagrant’s NFS.
First-class Apple Silicon support — Lima runs natively on M-series chips.
Smaller memory footprint — no VirtualBox overhead.

The tradeoff: Lima is macOS and Linux only. Windows users need an alternative (WSL2-based setups, Docker, or remote development).

Installing Lima for Trellis

On macOS, via Homebrew:

brew install lima

On Linux, check your distribution’s package manager or install from the Lima installation docs.

Trellis-CLI 1.16+ (December 2025) includes first-class Lima support. Update it:

brew upgrade trellis-cli

Verify:

lima --version
trellis --version

Starting a Trellis Dev VM with Lima

From your Trellis project directory:

trellis vm start

On first run, Trellis:

Downloads an Ubuntu 24.04 Lima VM image (2–3 GB).
Starts the VM with VirtioFS-mounted project directory.
Provisions the VM using the same Ansible playbooks as production (nginx, PHP, MariaDB, Redis).
Imports site configuration from group_vars/development/wordpress_sites.yml.
Updates your /etc/hosts so the dev hostnames resolve to the VM’s IP.

Total time from zero to working dev environment: 5–10 minutes on a modern Mac, most of that spent downloading the base image. Subsequent trellis vm start runs on the same machine take under 30 seconds.

Related commands:

trellis vm stop — shut down the VM.
trellis vm destroy — delete the VM entirely (use when switching projects or resetting).
trellis vm ssh — SSH into the running VM.
trellis vm shell — open a shell in the VM (context-aware, sets you in the right directory).

Migrating an Existing Trellis Project from Vagrant to Lima

If your Trellis project was created before Trellis 1.28 (when Vagrant support was dropped), the project still has Vagrant artifacts that need cleaning up.

Step 1 — Shut Down the Vagrant VM

Save any local database changes you need, then destroy the Vagrant VM:

vagrant halt
vagrant destroy -f

Step 2 — Update Trellis

In your project’s trellis/ directory, pull the latest Trellis release:

cd trellis
git remote add upstream https://github.com/roots/trellis.git
git fetch upstream
git merge upstream/main

Resolve any conflicts. The biggest structural changes are in Vagrantfile (deleted), bin/ (Lima helpers added), and requirements.txt (Lima-related Ansible collections).

Step 3 — Clean Up Vagrant Files

Delete Vagrantfile, .vagrant/ directory, and any other Vagrant-specific files. Commit the cleanup to your Trellis branch.

Step 4 — Install Lima and Update trellis-cli

See the installation steps above.

Step 5 — Start the Lima VM

trellis vm start

If you need to restore database data from the old Vagrant VM, export it before destroying the VM (wp db export) and import after the Lima VM is up.

The Day-to-Day Lima Workflow

Once the VM is running, the day-to-day experience is nearly identical to Vagrant:

Visit your dev URLs (example.test, etc.) in the browser. Same as before.
Edit code on the host — changes appear instantly in the VM via VirtioFS mount.
Run wp-cli in the VM via trellis vm shell.
Run composer in the VM similarly.
View logs with trellis vm shell and tail the usual nginx/PHP-FPM log files.

The differences you’ll notice:

VM starts and stops much faster — seconds, not minutes.
File I/O feels faster — working with large media libraries is dramatically less painful.
Less CPU and memory usage — Lima’s overhead is smaller than VirtualBox’s.
No VirtualBox update prompts ever again.

What About Windows?

Lima doesn’t run natively on Windows. Options for Windows developers using Trellis:

Run Lima inside WSL2. Install WSL2, install Lima inside the WSL2 distribution, use Trellis from there. This is the official recommended path.
Use remote development. Run your dev environment on a cloud VM (Hetzner, DigitalOcean), connect with VS Code Remote or Cursor Remote.
Use a different local tool like LocalWP or DevKinsta for dev, and still use Trellis for remote provisioning and deploys.

None of these are as clean as the macOS Lima experience, which is the one concrete tradeoff the Vagrant-to-Lima switch created.

Common Issues and Fixes

VM Won’t Start

Check limactl list to see VM state. Common causes:

Port conflict — another service is using the VM’s forwarded ports. Stop the other service or change Lima’s port mapping.
Disk space — Lima VMs need 10+ GB of free space.
Virtualization disabled — check your Mac’s System Settings or BIOS.

File Changes Not Syncing

Rarely happens with VirtioFS. If it does, restart the VM (trellis vm restart). If persistent, check the Lima VM’s mount configuration.

Slow File Operations

VirtioFS is usually fast, but some workloads (searching large directories, running composer in a huge project) can still be slower than native. Two mitigations: work on the VM directly for heavy operations, or use Lima’s 9p mount type as an alternative to VirtioFS in lima.yaml.

SSL Certificate Issues

Trellis generates self-signed SSL certs for local dev. Import them into your macOS Keychain (Trellis provides a script) to avoid browser warnings. This isn’t Lima-specific but comes up more often with fresh VM setups.

Frequently Asked Questions

Can I still use Vagrant with Trellis?

Not on Trellis 1.31+. The Vagrantfile was removed entirely. You can pin to Trellis 1.30.x if you need Vagrant temporarily, but it’s a dead-end branch with no upstream fixes.

Does Lima work on Intel Macs?

Yes. Lima supports both Intel and Apple Silicon Macs. Apple Silicon is where Lima shines most (compared to VirtualBox’s poor ARM support), but Intel Macs get the same speed and reliability benefits.

What about Docker for local WordPress development?

Docker is a viable alternative. It’s what DevKinsta and LocalWP use internally. Trellis chose Lima specifically because Lima gives you a real Linux VM that matches production one-to-one, whereas Docker containers have subtle differences from the production nginx + PHP-FPM + MariaDB stack.

Can I run multiple Trellis projects at once?

Yes. Each project has its own Lima VM. Start one, stop it, start another. Or, if you have the memory, run multiple VMs concurrently.

What’s the disk space overhead per VM?

Roughly 3–5 GB for a base Ubuntu VM plus your project’s data. Much less than a VirtualBox equivalent, which often grew to 10+ GB over time.

Does the Lima switch affect production deploys?

No. Lima only replaces local development. Production provisioning and deploys are unchanged — same Ansible playbooks, same server setup, same trellis deploy workflow.

Faster Local Dev, Closer to Production

The Vagrant-to-Lima switch is a strict upgrade for macOS and Linux Trellis users. Faster boot, faster file sync, less overhead, no licensed hypervisors, no Ruby dependency. The only real cost is that Windows developers need WSL2 or an alternative workflow.

If you’ve been on the fence about migrating an older Trellis project to Lima, do it. The upgrade pays for itself in the first week of faster startup and less file-sync friction. If you’re new to Trellis, start on the latest version — Lima’s the only option and it’s a good one.

At Emnes, we migrated our 18-site Trellis monorepo to Lima in October 2025 and haven’t looked back. Daily developer startup time dropped noticeably, and the flaky NFS-sync bugs that plagued our Mac fleet disappeared.