Installation

ps-lando itself is a single npm package — npx ps-lando@latest <command> is the only invocation you need. Everything else on this page is about the host machine that runs Lando + Docker underneath.

Prerequisites

Drop your zips, pick what to install

Since 1.0.0 (1.0.0), ps-lando is zero-config and theme-agnostic: drop your theme + module zips into a folder, run ps-lando create, and the CLI walks you through two prompts:

1. Theme — select prompt listing every theme detected (zip with config/theme.{yml,xml} at depth 0 or 1) plus a None option.
2. Modules — multiselect prompt with every module zip detected (<name>/<name>.php or <name>/config.xml) pre-checked.

Pick what you want, hit enter, the CLI installs only what you selected. No --panda flag, no theme-specific binary, no scanning of PS-bundled modules sneaking in.

The CLI scans the cwd (or --zips=<dir>) and classifies every *.zip as theme / module / unknown via the bundled zip-classifier. Detection is case-insensitive everywhere.

Non-interactive (-y) defaults

ps-lando create -y skips both prompts:

• 1 theme detected → auto-selected. 2+ themes → exits 2 (AmbiguousThemeError) with a hint to pass --theme=<name>.
• All detected modules are auto-checked.
• Empty folder → vanilla PS install with the bundled classic / hummingbird themes (no prompts shown).

CI scripts that already pass -y keep working unchanged.

Panda happy path

Drop your panda*.zip + steasybuilder* + steasy_trans_panda* zips into the folder, run ps-lando create, select panda at the theme prompt, leave the module multiselect as-is, hit enter. The bundled panda preset activates automatically (it binds to the selected theme name) and you get the same Panda + Easy Builder sandbox the pre-1.0 hard-coded flow produced — byte-equivalent to v0.6.

Bundled panda preset

ps-lando ships a bundled panda preset that activates whenever the user selects (or -y auto-selects) a theme whose name is panda — the same Panda + Easy Builder behavior pre-1.0 users had hard-coded. The preset wires the Easy Builder ↔ Panda bridge and contributes the blog / easybuilder / social / marketing group globs. Disable with --no-preset or presets: [] in config; force a different preset with --preset=<name>.

See Reference → Presets for authoring local presets.

Optional: pslando.config.json

Zero-config is the default. If you want explicit, repeatable behavior (CI, monorepo subfolders, multi-theme drops), run ps-lando init to generate a pslando.config.json:

ps-lando init           # interactive (clack), 7 prompts
ps-lando init --yes     # write defaults, no prompts
ps-lando init --force   # overwrite existing config

The init wizard writes pslando.config.json, an example init-scripts/01-example.sh, and appends .pslando-cache.json to your .gitignore. See Reference → Config for the full schema.

macOS

The most-tested platform. Works natively on Apple Silicon (M1 / M2 / M3 / M4) — Docker images run natively or via Rosetta seamlessly.

brew install node
brew install --cask docker
brew install --cask lando

Start Docker Desktop once from Applications so it accepts permissions and creates ~/.docker/. After that, Lando handles starting/stopping containers as needed.

node --version    # v20+ expected
docker --version  # any recent version
lando version

Linux

Works on any distro that can run Docker Engine + Node 20. The setup is per-distro for Docker, then Lando provides a single deb/rpm package.

Ubuntu / Debian

1. Install Docker Engine (community edition, free):

Add Docker's official APT repo and install:

# Remove any old podman/docker.io packages first
sudo apt-get remove docker docker-engine docker.io containerd runc 2>/dev/null

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

For Debian, swap ubuntu for debian in the URLs above.

2. Run Docker without sudo:

sudo usermod -aG docker $USER
newgrp docker     # apply the group in current shell, or log out + back in
docker run hello-world

3. Install Node.js 20:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

4. Install Lando:

Grab the latest .deb from lando releases:

curl -fsSL https://files.lando.dev/installer/setup-lando.sh | bash
# or download lando-stable.deb manually and:
# sudo dpkg -i lando-stable.deb

Fedora / RHEL / CentOS Stream

# Docker
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER && newgrp docker

# Node.js 20
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs

# Lando
curl -fsSL https://files.lando.dev/installer/setup-lando.sh | bash

Arch / Manjaro

sudo pacman -Syu docker docker-buildx docker-compose nodejs npm
sudo systemctl enable --now docker
sudo usermod -aG docker $USER && newgrp docker

# Lando — install via the official setup script
curl -fsSL https://files.lando.dev/installer/setup-lando.sh | bash

Verify Linux install

node --version       # v20+
docker --version
docker compose version
lando version
docker run --rm hello-world   # confirms daemon + permissions

Common Linux gotchas

• Cannot connect to the Docker daemon — you forgot sudo usermod -aG docker $USER (or didn't run newgrp docker / log out+in after).
• failed to start daemon: error initializing graphdriver — almost always a cgroup v2 issue on older kernels. Update to kernel 5.15+ or check /etc/docker/daemon.json.
• Lando port conflicts — if you already run Apache or MySQL on the host, lando start will fail. Stop the host services or change Lando's exposed ports in .lando.yml.
• SELinux on Fedora/RHEL — if mounts behave oddly, try :Z on bind mounts. Lando handles this internally for its own services.

Windows

Use WSL2 with Docker Desktop's WSL integration. ps-lando uses POSIX tools (unzip, curl, git) and assumes a Unix shell — running it from PowerShell or CMD won't work.

One-time setup

1. Install WSL2 + Ubuntu (admin PowerShell, one command):

wsl --install

This installs WSL2 and sets Ubuntu as the default distro. Reboot when prompted, then open Ubuntu from Start. Set a username + password the first time it launches.

If you want a different distro: wsl --list --online shows available ones, wsl --install -d <Name> installs the one you pick.

2. Update WSL after the first launch:

wsl --update
wsl --set-default-version 2

3. Install Docker Desktop:

Download from docker.com. After install, open Settings:

• General → check "Use the WSL 2 based engine".
• Resources → WSL Integration → enable for your Ubuntu distro.
• Apply + restart.

Verify from inside WSL Ubuntu:

docker version            # should show Server: Docker Desktop
docker run hello-world

4. Install Node 20 + Lando inside WSL:

# Inside the WSL Ubuntu shell:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

curl -fsSL https://files.lando.dev/installer/setup-lando.sh | bash

Where to put your project files

Inside the WSL filesystem (e.g. /home/<user>/projects/my-shop), not on the Windows side (/mnt/c/Users/...). Cross-filesystem I/O across the WSL boundary is 5–10× slower and breaks file watchers in Lando.

cd ~                           # /home/<user>/
mkdir -p projects/my-shop
cd projects/my-shop
cp /mnt/c/Users/<you>/Downloads/panda-theme.zip .
npx ps-lando@latest create

If you use VS Code, install the WSL extension. Open the project with File → Open Folder in WSL so the editor talks to the Linux filesystem natively.

Verify Windows install

From the WSL Ubuntu shell:

node --version        # v20+
docker --version      # the Docker Desktop server
lando version

Common Windows gotchas

• docker: command not found inside WSL — Docker Desktop's WSL integration isn't enabled for that distro. Settings → Resources → WSL Integration.
• lando start hangs at "starting Docker" — make sure Docker Desktop is actually running on Windows (system tray icon). WSL can't start it on its own.
• Files saved in Windows aren't picked up by Lando — your project lives on /mnt/c/.... Move it to /home/<user>/... and re-create the sandbox.
• exec format error — your WSL is still on WSL1. Run wsl --set-version Ubuntu 2 from PowerShell.

First run — what to expect

The first ps-lando create on a fresh machine will be a few minutes slower than later runs. Docker pulls the LAMP recipe images on first start; subsequent sandboxes reuse those cached images.

Both PS 8.2.x and PS 9.1.x land in roughly the same window — PS 9 pulls the pre-built edition from the official PrestaShop CDN (no Composer inside Lando required since 0.3.0).

Verify your install

Once the prereqs are in place, you don't need to install ps-lando separately. npx handles it:

npx ps-lando@latest --version

Optional: pin a global install if you don't want to wait for npx every time.

npm i -g ps-lando
ps-lando --version

Next steps