Installation

Linux

Requires systemd

Lerd runs every container as a Podman Quadlet and every worker as a systemd user service, so a systemd-based distro is required. OpenRC (Gentoo, Artix-openrc, Alpine), runit (Void, Artix-runit), s6, and sysvinit-based distros (Devuan) are not supported.

Tested and known-good: Ubuntu, Fedora, Arch, Debian, Mint, Pop!_OS, openSUSE, CachyOS, Omarchy. Any systemd distro should work.

One-line installer (recommended)

curl

curl -fsSL https://lerd.sh/install.sh | bash

wget

wget -qO- https://lerd.sh/install.sh | bash

From source

git clone https://github.com/geodro/lerd
cd lerd
make build
make install            # installs to ~/.local/bin/lerd
make install-installer  # installs lerd-installer to ~/.local/bin/

The installer will:

• Check and offer to install missing prerequisites (Podman, NetworkManager, unzip)
• Download the latest lerd binary for your architecture (amd64 / arm64)
• Install it to ~/.local/bin/lerd
• Add ~/.local/bin to your shell's PATH (bash, zsh, or fish)
• Automatically run lerd install to complete environment setup

DNS setup requires sudo

lerd install writes to /etc/NetworkManager/dnsmasq.d/ and /etc/NetworkManager/conf.d/ and restarts NetworkManager. This is the only step that requires sudo.

After install, reload your shell or open a new terminal so PATH takes effect.

lerd install will:

1. Create XDG config and data directories
2. Create the lerd Podman network
3. Download static binaries: Composer, fnm, mkcert
4. Install the mkcert CA into your system trust store
5. Write and start the lerd-dns and lerd-nginx Podman Quadlet containers
6. Enable the lerd-watcher background service (auto-discovers new projects)
7. Add ~/.local/share/lerd/bin to your shell's PATH

---

Install from a local build

If you built from source and want to skip the GitHub download:

make build
bash install.sh --local ./build/lerd

---

Update

lerd update

Fetches the latest release from GitHub, downloads the binary for your architecture, and atomically replaces the running binary. No restart needed.

You can also re-run the installer:

curl

curl -fsSL https://lerd.sh/install.sh | bash -s -- --update

wget

wget -qO- https://lerd.sh/install.sh | bash -s -- --update

---

Uninstall

lerd uninstall

Stops all containers, disables and removes Quadlet units, removes the watcher service, removes the binary, tears down the lerd podman network (including aardvark-dns runtime state), and cleans up the PATH entry from your shell config.

Four opt-in prompts before finishing:

1. Remove all config and data — deletes ~/.config/lerd and ~/.local/share/lerd (takes your sites.yaml, bundled binaries, TLS certs, and all service data with it).
2. Remove MCP integration — unregisters lerd from Claude Code, Cursor, Windsurf, and Junie at user scope, removes ~/.claude/skills/lerd/, ~/.cursor/rules/lerd.mdc, and strips the lerd block from ~/.junie/guidelines.md. Also runs across every registered site to clean the same files per-project.
3. Uninstall mkcert CA — runs mkcert -uninstall so browsers and OS trust stores stop trusting the lerd CA that install originally added.
4. Purge lerd-built container images — removes lerd-php*-fpm:local, lerd-custom-*:local, and lerd-dnsmasq:local. Upstream pulled images (mysql/redis/postgres/etc.) are deliberately left alone; they're expensive to re-pull and your database/app data lives in host bind mounts, not inside the images, so nothing is lost by keeping them.

To answer yes to every prompt without interaction:

lerd uninstall --force

---

Check prerequisites only

bash install.sh --check

---

macOS

Install via the Homebrew tap:

brew install geodro/lerd/lerd
lerd install

Podman is installed automatically as a Homebrew dependency. lerd install sets up Podman Machine, DNS, and nginx on first run.

Update:

brew upgrade lerd
lerd install

Uninstall:

lerd uninstall
brew uninstall lerd

Windows (beta)

There is no native Windows build. Lerd runs on Windows through WSL2, where the standard Linux build works unchanged once systemd and rootless Podman are set up. Windows support is beta, it works well for daily development but gets less testing than native Linux or macOS. See the Windows (WSL2) guide for the full walkthrough, including the events_logger Podman tweak and the mkcert root CA export to the Windows trust store.