Prerequisites

Before you run LocalEmu, three things must be in place on your machine: a recent Python interpreter, the Docker daemon, and the right pip install command. This page walks through each one, explains why it matters, and shows you how to verify it before you move on.

1. Python 3.10 or newer

LocalEmu's pyproject.toml declares requires-python = ">=3.10". The active development target is Python 3.13, but 3.10, 3.11, and 3.12 all work in production and CI.

$ python3 --version
Python 3.13.12

If the command prints command not found or a version older than 3.10, install a recent Python first:

• macOS: brew install python@3.13, or download from python.org.
• Debian / Ubuntu: sudo apt install python3.13 python3.13-venv.
• Fedora / RHEL: sudo dnf install python3.13.

Always install LocalEmu inside a virtualenv (python3 -m venv .venv && source .venv/bin/activate) so its dependencies stay isolated from your system Python.

2. Docker

Docker is required for the ten services whose behavior is backed by real containers (full list in section 3). The emulator itself runs on the host as a normal Python process, but when you call (for example) RunInstances the EC2 backend asks the Docker daemon to start a real container that plays the role of the EC2 instance. No daemon, no container, no instance. Same story for Lambda invocations, ECS tasks, RDS engines, and the other seven.

$ docker --version
Docker version 29.4.3, build d600e0e

$ docker ps
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

LocalEmu is tested against Docker 24.x and newer. Older versions may work but are not exercised in CI. The daemon must be running: docker ps returns non-zero exit status if it is not.

Install Docker on your platform

• macOS (Intel and Apple Silicon): install Docker Desktop and launch it once so the background daemon starts. Default resource limits (2 CPU, 4 GB RAM) are enough for LocalEmu; bump the RAM if you plan to run EKS, multiple RDS engines, or large user workloads in parallel.
• Linux: install Docker Engine from your distro or from docker.com, then add your user to the docker group so docker ps works without sudo (otherwise LocalEmu, which runs as your user, cannot reach the daemon).
• Windows: install Docker Desktop with the WSL2 backend enabled (the default since Docker Desktop 4.x), then run LocalEmu from inside your WSL2 distribution (Ubuntu, Debian, etc.). Native Windows Python is not a supported configuration.

3. What works without Docker

Most of the AWS services LocalEmu emulates are implemented in pure Python and run inside the LocalEmu process itself. Calls to those services succeed even if the Docker daemon is down, absent, or you simply forgot to start it. The ten services in the right-hand column below are the exceptions: they each need a real container to provide real behavior, so they will return errors (or fall back to metadata-only) if Docker is unreachable.

If you call run-instances without a running Docker daemon, LocalEmu logs a warning and falls back to a metadata-only response: the EC2 API answers, but no container starts and you cannot SSH in. To make the fallback explicit (so you never accidentally trust a "running" instance that does not exist), set EC2_VM_MANAGER=none before starting LocalEmu. The EC2 API still answers Describe / Run / Terminate calls, but the metadata-only mode is opt-in and unambiguous.

4. Which pip install do you want?

LocalEmu ships five different install variants (called "extras" in Python packaging). Each extra is a superset of the previous one, except for the bare install which is the smallest. Pick one based on what you plan to do. If you are not sure, the answer is [runtime].

The bare install (avoid)

$ pip install localemu
# Installs the package metadata + the localemu / awsemu / lpm
# entry-points, but NOT the runtime stack. ``localemu start``
# will fail with ImportError. Use [runtime] instead.

The runtime install (recommended)

$ pip install "localemu[runtime]"
# The one most users want. Brings in:
#   - the full AWS service stack (moto-ext, boto3, botocore)
#   - awscli (so the awsemu wrapper has something to call)
#   - the Athena DuckDB engine, antlr parsers, jinja, etc.

The test install

$ pip install "localemu[test]"
# Everything in [runtime] + pytest, coverage, pika (for the MQ
# round-trip), kafka-python (for MSK), aws-cdk-lib. Needed only
# if you plan to run the LocalEmu test suite.

The dev install

$ pip install "localemu[dev]"
# Everything in [test] + ruff, mypy, pre-commit, deptry, Cython,
# pypandoc. The set used by LocalEmu contributors.

Note on awscli. The awsemu CLI that ships with LocalEmu is a thin wrapper that prepends --endpoint-url=http://localhost:4566 to every command and then shells out to the real aws binary. The [runtime] extra pins awscli==1.44.49 as a hard dependency, so the binary is installed for you. You do not need to run pip install awscli separately, and you should not, because LocalEmu pins a specific version that the wrapper is tested against.

5. The three CLIs LocalEmu ships

Installing localemu[runtime] puts three commands on your PATH. Each one has a single, narrow job. None of them is mandatory in the sense that you must use it, but they exist to remove friction. Anything they do, you can also do with the upstream tool directly if you prefer.

The pattern. Each LocalEmu CLI is opt-in convenience around a standard tool (server / AWS CLI / package install). They exist so that someone new to LocalEmu can run their first command in 30 seconds without configuring anything. Once you are comfortable, point your existing aws CLI, boto3 scripts, Terraform, or CDK at AWS_ENDPOINT_URL=http://localhost:4566 and you never have to think about the wrappers again.

6. Verify the install end-to-end

Three quick commands confirm that all three prerequisites are wired up correctly: Python is the right version, Docker is reachable, and LocalEmu can answer an AWS API call.

$ python3 --version && docker info >/dev/null 2>&1 && pip show localemu >/dev/null && echo READY
Python 3.13.12
READY

$ localemu start
...
Ready.

$ awsemu sts get-caller-identity
{
    "UserId": "AKIAIOSFODNN7EXAMPLE",
    "Account": "000000000000",
    "Arn": "arn:aws:iam::000000000000:root"
}

If all three commands succeed, you are ready. Continue to Installation for a full walkthrough, or jump straight to Quick Start and run your first AWS call against the local emulator.

7. Platform notes

macOS (Intel and Apple Silicon)

First-class target. Docker Desktop runs the daemon inside a Linux VM, which means container bridge IPs are not directly routable from your Mac. LocalEmu accounts for this: the EIP data plane binds 127.0.0.1 and tunnels into the container via docker exec, so reaching an EC2 instance from the host always works regardless of the underlying network topology.

Linux (native Docker)

Smoothest path. The Docker daemon and LocalEmu share the same kernel, so container bridge IPs are routable from the host directly. Everything in the EIP, SG, and NACL paths still works through loopback for parity with macOS, so any test or demo you write on Linux behaves the same way on a teammate's Mac.

Windows (WSL2)

Install Docker Desktop with the WSL2 backend enabled, then run LocalEmu from inside your WSL2 distribution (not from PowerShell or cmd). Native Windows Python is not a supported configuration. From inside WSL2, treat the rest of these docs as Linux instructions: the same commands work unchanged.