Get Started

LocalStack is a cloud service emulator that runs in a single container on your laptop or in your CI environment. With LocalStack, you can run your AWS applications or Lambdas entirely on your local machine without connecting to a remote cloud provider! Whether you are testing complex CDK applications or Terraform configurations, or just beginning to learn about AWS services, LocalStack helps speed up and simplify your testing and development workflow.

LocalStack supports a growing number of AWS services, like AWS Lambda, S3, DynamoDB, Kinesis, SQS, SNS, and many more! The Pro version of LocalStack supports additional APIs and advanced features. You can find a comprehensive list of supported APIs on our ⭐ Feature Coverage page.

LocalStack also provides additional features to make your life as a cloud developer easier! Check out LocalStack’s Cloud Developer Tools.

Get LocalStack Up and Running

The first thing when getting started with LocalStack is to choose your preferred way of starting and managing your LocalStack instance.
LocalStack currently provides the following options:

• LocalStack CLI
  The easiest way to start and manage LocalStack - either on your machine, in a Docker container on your machine, or even on a remote Docker host.

• LocalStack Cockpit
  Get a desktop experience and work with your local LocalStack instance via the UI.

• Docker
  Use the docker CLI to manually start the LocalStack Docker container.

• Docker-Compose
  Use docker-compose to configure and start your LocalStack Docker container.

• Helm
  Use helm to create a LocalStack deployment in a Kubernetes cluster.

LocalStack CLI

The LocalStack CLI aims to simplify starting and managing LocalStack. It provides convenience features to start LocalStack on your local machine, as a Docker container on your machine, or even on a remote Docker host. In addition you can easily check the status or open a shell in your LocalStack instance if you want to take a deep-dive.

Prerequisites

Please make sure to install the following tools on your machine before moving on:

• python (Python 3.6 up to 3.10 is supported)
• pip (Python package manager)
• docker

Installation

The easiest way to install the LocalStack CLI is via pip:

$ python3 -m pip install localstack

Afterwards you should be able to use the LocalStack CLI in your terminal:

$ localstack --help
Usage: localstack [OPTIONS] COMMAND [ARGS]...

  The LocalStack Command Line Interface (CLI)

Options:
...

Troubleshooting

The installation is successful, but I cannot execute localstack on my terminal.

If you can successfully install LocalStack using pip but you cannot use it in your terminal, you most likely haven’t set up your operating system’s / terminal’s PATH variable (in order to tell them where to find programs installed via pip).

• If you are using Windows, you can enable the PATH configuration when installing Python, as described in the official docs of Python.
• If you are using a MacOS or Linux operating system, please make sure that the PATH is correctly set up - either system wide, or in your terminal.

As a workaround you can call the LocalStack CLI python module directly:

$ python3 -m localstack.cli.main

Updating LocalStack using pip does not work

If you get a error message containing:

ImportError: module 'plugin.setuptools' has no attribute 'load_plux_entrypoints'

You might need to execute additional steps to upgrade the LocalStack CLI. Push the following command on your terminal:

$ pip uninstall localstack-plugin-loader

Reinstall LocalStack afterwards using the following command:

$ pip install --force-reinstall localstack plux

It will fix the dependency conflict. After this, LocalStack should be updateable in the future. As an alternative, if you are using a virtual environment, please delete it and create a new one, for a clean installation.

Starting LocalStack with the LocalStack CLI

By default, LocalStack is started inside a Docker container by running:

$ localstack start

LocalStack Cockpit

See LocalStack Cockpit.

Docker

If you do not want to use the LocalStack CLI, you can also decide to manually start the LocalStack Docker container.

Prerequisites

Please make sure that you have a working docker environment on your machine before moving on. You can check if docker is correctly configured on your machine by executing docker info in your terminal. If it does not report an error (but shows information on your Docker system), you’re good to go.

Starting LocalStack with Docker

You can start the Docker container simply by executing the following docker run command:

$ docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack

Docker-Compose

If you want to manually manage your Docker container, it’s usually a good idea to use docker-compose in order to simplify your container configuration.

Prerequisites

• docker
• docker-compose (version 1.9.0+)

Starting LocalStack with Docker-Compose

You can use the docker-compose.yml file from the official LocalStack repository and use this command (currently requires docker-compose version 1.9.0+):

$ docker-compose up

Please note that there’s a few pitfalls when configuring your stack manually via docker-compose (e.g., required container name, Docker network, volume mounts, environment variables, etc.). We recommend using the LocalStack CLI to validate your configuration, which will print warning messages in case it detects any (potential) misconfigurations:

$ localstack config validate
...

Helm

If you want to deploy LocalStack in your Kubernetes cluster, you can use Helm.

Prerequisites

• Kubernetes
• Helm

Deploy LocalStack using Helm

You can deploy LocalStack in a Kubernetes cluster by running these commands:

$ helm repo add localstack-repo https://helm.localstack.cloud
$ helm upgrade --install localstack localstack-repo/localstack

The Helm charts are not maintained in the main repository, but in a separate one.

Ran into trouble?

We strive to make it as easy as possible for you to use LocalStack, and we are very grateful for any feedback. If you run into any issues or problems with this guide, please submit an issue.

What’s next?

Now that you have LocalStack up and running, the following resources might be useful for your next steps:

• Use the LocalStack integrations to interact with LocalStack and other integrated tools, for example:
  • Use awslocal to use the AWS CLI against your local cloud!
  • Use the Serverless Framework with LocalStack!
  • And many more!
• Find out how to configure LocalStack such that it perfectly fits your need.
• Use LocalStack in your CI environment to increase your code quality.
• Checkout LocalStack’s Cloud Developer Tools to further increase your development efficiency with LocalStack.
• Find out about the ways you can configure LocalStack.