macOS (Apple Silicon)

On Apple Silicon (M1/M2/M3…), the recommended way to run Speculos is the Docker image. The official image is multi-arch, so it runs natively on arm64 — you no longer need to edit the Dockerfile or pick a special -aarch64 builder.

Prefer a native install? pip install speculos also works on Apple Silicon; see the Quickstart. Use Docker if you hit dependency issues.

Pull the image

docker pull ghcr.io/ledgerhq/speculos:latest
docker image tag ghcr.io/ledgerhq/speculos:latest speculos

Run an app

Mount your apps folder and publish the API port; then open the web UI at http://127.0.0.1:5000:

docker run --rm -it \
  -v "$(pwd)"/apps:/speculos/apps \
  -p 5000:5000 \
  speculos --display headless --api-port 5000 apps/boil.elf

The app folder ($(pwd)/apps/) is mounted with -v.

Using VNC instead of the web UI

docker run --rm -it \
  -v "$(pwd)"/apps:/speculos/apps \
  -p 41000:41000 \
  speculos --display headless --vnc-port 41000 apps/boil.elf

macOS Screen Sharing requires a password: add --vnc-password <pwd>.

Build the image from source (optional)

Only needed if you are modifying Speculos itself. The build is the same on all architectures:

docker build ./ -t speculos

More

All speculos.py arguments can be passed on the Docker command line; see the general Docker page for docker-compose, debugging and the full argument list.
Troubleshooting covers common Docker/macOS issues.