Installation
LocalStack CLI
The quickest way get started with LocalStack is by using the LocalStack CLI. It allows you to start LocalStack from your command line.
-Please make sure that you have a working docker
environment on your machine before moving on.
The CLI starts and manages the LocalStack docker container. -For alternative methods of managing the LocalStack container, see our alternative installation instructions.
$ brew install localstack/tap/localstack-cli
Alternative: Binary Download
Alternatively, you can download the respective binary for your architecture directly:
or use this curl
command:
$ curl -Lo localstack-cli-3.5.0-darwin-amd64-onefile.tar.gz \
- https://github.com/localstack/localstack-cli/releases/download/v3.5.0/localstack-cli-3.5.0-darwin-amd64-onefile.tar.gz
Then extract the LocalStack CLI from the terminal:
$ sudo tar xvzf localstack-cli-3.5.0-darwin-*-onefile.tar.gz -C /usr/local/bin
Alternative: Python
You can also install the LocalStack CLI directly in your Python environment.Please make sure to install the following tools on your machine before moving ahead:
Afterwards you can install the LocalStack CLI in your Python environment with:
$ python3 -m pip install --upgrade localstack
Warning
Do not usesudo
or the root
user - LocalStack should be installed and started entirely under a local non-root user.
-If you have problems with permissions in MacOS X Sierra, install with python3 -m pip install --user localstack
.You can download the respective binary for your architecture directly:
or use this curl
command:
For x86-64
:
$ curl -Lo localstack-cli-3.5.0-linux-amd64-onefile.tar.gz \
- https://github.com/localstack/localstack-cli/releases/download/v3.5.0/localstack-cli-3.5.0-linux-amd64-onefile.tar.gz
Or ARM64
:
$ curl -Lo localstack-cli-3.5.0-linux-arm64-onefile.tar.gz \
- https://github.com/localstack/localstack-cli/releases/download/v3.5.0/localstack-cli-3.5.0-linux-arm64-onefile.tar.gz
Then extract the LocalStack CLI from the terminal:
$ sudo tar xvzf localstack-cli-3.5.0-linux-*-onefile.tar.gz -C /usr/local/bin
Alternative: Homebrew on Linux
Alternatively, if you are using Homebrew for Linux, you can install the LocalStack CLI directly from our official LocalStack tap:$ brew install localstack/tap/localstack-cli
Alternative: Python
You can also install the LocalStack CLI directly in your PYthon environment.Please make sure to install the following tools on your machine before moving ahead:
Afterwards you can install the LocalStack CLI in your Python environment with:
$ python3 -m pip install --upgrade localstack
Warning
Do not usesudo
or the root
user - LocalStack should be installed and started entirely under a local non-root user.Then extract the archive and execute the binary using Powershell.
Alternative: Python
You can also install the LocalStack CLI directly in your Python environment.Please make sure to install the following tools on your machine before moving ahead:
Afterwards you can install the LocalStack CLI in your Python environment with:
$ python3 -m pip install --upgrade localstack
Warning
Do not usesudo
or the root
user - LocalStack should be installed and started entirely under a local non-root user.Please make sure to install the following tools on your machine before moving ahead:
Afterwards you can install the LocalStack CLI in your Python environment with:
$ python3 -m pip install --upgrade localstack
Note
To download a specific version of LocalStack, check out our release page and download it in the following manner:
$ python3 -m pip install localstack==<version>
Here <version>
depicts the particular LocalStack version that you would like to download and use.
Warning
Do not usesudo
or the root
user - LocalStack should be installed and started entirely under a local non-root user.To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal:
$ localstack --version
-3.5.0
You are all set! -To use all of LocalStack’s features we recommend to get a LocalStack account and set up your auth token. -Afterwards, check out our Quickstart guide to start your local cloud!
Alternatives
Besides using the CLI, there are other ways of starting and managing your LocalStack instance:
LocalStack Desktop
Get a desktop experience and work with your local LocalStack instance via the UI.LocalStack Docker Extension
Use the LocalStack extension for Docker Desktop to work with your LocalStack instance.Docker-Compose
Usedocker-compose
to configure and start your LocalStack Docker container.Docker
Use thedocker
CLI to manually start the LocalStack Docker container.Helm
Usehelm
to create a LocalStack deployment in a Kubernetes cluster.
LocalStack runs inside a Docker container, and the above options are different ways to start and manage the LocalStack Docker container. -For a comprehensive overview of the LocalStack images, check out our Docker images documentation.
LocalStack Desktop
Download our desktop client at app.localstack.cloud/download. -See LocalStack Desktop.
LocalStack Docker Extension
Install our official Docker Desktop extension to manage LocalStack. -See LocalStack Docker Extension.
Docker-Compose
To use LocalStack without the LocalStack CLI, you have the option of running the LocalStack Docker container by yourself.
-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 start LocalStack with Docker Compose by configuring a docker-compose.yml
file.
-Currently, docker-compose
version 1.9.0+ is supported.
Table of Contents
Categories
Persistence
Installation
LocalStack CLI
The quickest way get started with LocalStack is by using the LocalStack CLI. It allows you to start LocalStack from your command line. +Please make sure that you have a working Docker installation on your machine before moving on.
The CLI starts and manages the LocalStack Docker container. +For alternative methods of managing the LocalStack container, see our alternative installation instructions.
You can download the pre-built binary for your architecture using the link below:
or use the curl commands below:
For x86-64:
$ curl --output localstack-cli-3.5.0-linux-amd64-onefile.tar.gz \
+ --location https://github.com/localstack/localstack-cli/releases/download/v3.5.0/localstack-cli-3.5.0-linux-amd64-onefile.tar.gz
For ARM64:
$ curl --output localstack-cli-3.5.0-linux-arm64-onefile.tar.gz \
+ --location https://github.com/localstack/localstack-cli/releases/download/v3.5.0/localstack-cli-3.5.0-linux-arm64-onefile.tar.gz
Then extract the LocalStack CLI from the terminal:
$ sudo tar xvzf localstack-cli-3.5.0-linux-*-onefile.tar.gz -C /usr/local/bin
Alternative: Homebrew on Linux
If you are using Homebrew for Linux, you can install the LocalStack CLI directly from our official LocalStack tap:
$ brew install localstack/tap/localstack-cli
You can install the LocalStack CLI using Brew directly from our official LocalStack tap:
$ brew install localstack/tap/localstack-cli
Alternative: Binary Download
You may download the binary for your architecture using the link below:
or use the following curl command:
$ curl --output localstack-cli-3.5.0-darwin-amd64-onefile.tar.gz \
+ --location https://github.com/localstack/localstack-cli/releases/download/v3.5.0/localstack-cli-3.5.0-darwin-amd64-onefile.tar.gz
Then extract the LocalStack CLI from the terminal:
$ sudo tar xvzf localstack-cli-3.5.0-darwin-*-onefile.tar.gz -C /usr/local/bin
You can download the pre-built binary for your architecture using the link below:
Then extract the archive and execute the binary in Powershell.
If you cannot use the binary releases of LocalStack, you can install the Python distribution.
Please make sure to install the following before moving ahead:
Next install the LocalStack CLI in your Python environment by running:
$ python3 -m pip install --upgrade localstack
Note
To download a specific version of LocalStack, replace <version>
with the required version from release page.
$ python3 -m pip install localstack==<version>
Tip
If you have problems with permissions in MacOS X Sierra, install with:
$ python3 -m pip install --user localstack
Warning
Do not usesudo
or the root
user when starting LocalStack.
+It should be installed and started entirely under a local non-root user.To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal:
$ localstack --version
+3.5.0
You are all set!
To use all of LocalStack’s features we recommend to get a LocalStack account and set up your auth token. +Afterwards, check out our Quickstart guide to start your local cloud!
Alternatives
Besides using the CLI, there are other ways of starting and managing your LocalStack instance:
LocalStack Desktop
Get a desktop experience and work with your local LocalStack instance via the UI.LocalStack Docker Extension
Use the LocalStack extension for Docker Desktop to work with your LocalStack instance.Docker-Compose
Use Docker Compose to configure and start your LocalStack Docker container.Docker
Use the Docker CLI to manually start the LocalStack Docker container.Helm
Use Helm to create a LocalStack deployment in a Kubernetes cluster.
LocalStack runs inside a Docker container, and the above options are different ways to start and manage the LocalStack Docker container. +For a comprehensive overview of the LocalStack images, check out our Docker images documentation.
LocalStack Desktop
Learn more about our desktop client at LocalStack Desktop and download it here.
LocalStack Docker Extension
Install our official Docker Desktop extension to manage LocalStack. +See LocalStack Docker Extension for more information.
Docker-Compose
To use LocalStack without the LocalStack CLI, you have the option of running the LocalStack Docker container by yourself. +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 start LocalStack with Docker Compose by configuring a docker-compose.yml
file.
+Docker Compose v1.9.0 and above is supported.
version: "3.8"
@@ -374,30 +371,30 @@
volumes:
- "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
- "/var/run/docker.sock:/var/run/docker.sock"
Start the container by running the following command:
$ docker-compose up
Note
This command pulls the current nightly build from the
master
branch (if you don’t have the image locally) and not the latest supported version. -If you want to use a specific version, set the appropriate localstack image tag atservices.localstack.image
in thedocker-compose.yml
file (for examplelocalstack/localstack:<version>
).If you are using LocalStack with an auth token, you need to specify the image tag as
localstack/localstack-pro
in thedocker-compose.yml
file. +If you want to use a specific version, set the appropriate LocalStack image tag atservices.localstack.image
in thedocker-compose.yml
file (for examplelocalstack/localstack:<version>
).If you are using LocalStack with an auth token, you need to specify the image tag as
localstack/localstack-pro
in thedocker-compose.yml
file. Going forward,localstack/localstack-pro
image will contain our Pro-supported services and APIs.This command reuses the image if it’s already on your machine, i.e. it will not pull the latest image automatically from Docker Hub.
Mounting the Docker socket
/var/run/docker.sock
as a volume is required for some services that use Docker to provide the emulation, such as AWS Lambda. Check out the Lambda providers documentation for more information.To facilitate interoperability, configuration variables can be prefixed with
LOCALSTACK_
in docker. For instance, settingLOCALSTACK_PERSISTENCE=1
is equivalent toPERSISTENCE=1
.If using the Docker default bridge network using
network_mode: bridge
, container name resolution will not work inside your containers. Please consider removing it, if this functionality is needed.To configure an auth token, refer to the auth token documentation.
Please note that there are a few pitfalls when configuring your stack manually via docker-compose (e.g., required container name, Docker network, volume mounts, and environment variables). 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
...
Docker
You can also directly start the LocalStack container using the Docker CLI instead of Docker-Compose. -This method requires more manual steps and configuration, but it gives you more control over the container settings.
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.
+This method requires more manual steps and configuration, but it gives you more control over the container settings.
Prerequisites
Please make sure that you have a working Docker installation 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 127.0.0.1:4566:4566 \
- -p 127.0.0.1:4510-4559:4510-4559 \
- -v /var/run/docker.sock:/var/run/docker.sock \
- localstack/localstack
docker run \
- --rm -it \
- -p 127.0.0.1:4566:4566 \
- -p 127.0.0.1:4510-4559:4510-4559 \
- -p 127.0.0.1:443:443 \
- -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
- -v /var/run/docker.sock:/var/run/docker.sock \
- localstack/localstack-pro
Note
This command pulls the current nightly build from the
master
branch (if you don’t have the image locally) and not the latest supported version. +Pro
$ docker run \
+ --rm -it \
+ -p 127.0.0.1:4566:4566 \
+ -p 127.0.0.1:4510-4559:4510-4559 \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ localstack/localstack
$ docker run \
+ --rm -it \
+ -p 127.0.0.1:4566:4566 \
+ -p 127.0.0.1:4510-4559:4510-4559 \
+ -p 127.0.0.1:443:443 \
+ -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ localstack/localstack-pro
Note
This command pulls the current nightly build from the
master
branch (if you don’t have the image locally) and not the latest supported version. If you want to use a specific version of LocalStack, use the appropriate tag:docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack:<tag>
. Check-out the LocalStack releases to know more about specific LocalStack versions.If you are using LocalStack with an auth token, you need to specify the image tag as
localstack/localstack-pro
in your Docker setup. Going forward,localstack/localstack-pro
image will contain our Pro-supported services and APIs.This command reuses the image if it’s already on your machine, i.e. it will not pull the latest image automatically from Docker Hub.
Mounting the Docker socket
/var/run/docker.sock
as a volume is required for some services that use Docker to provide the emulation, such as AWS Lambda. Check out the Lambda providers documentation for more information.When using Docker to manually start LocalStack, you will have to configure the container on your own (see docker-compose-pro.yml and Configuration). @@ -415,14 +412,13 @@ Commands: all Update all LocalStack components docker-images Update docker images LocalStack depends on - localstack-cli Update LocalStack CLI
Updating the LocalStack CLI itself (localstack update localstack-cli
and localstack update all
) is currently only supported if you installed the CLI in a Python environment.
-If you have installed the CLI with Brew or directly as a binary, please simply perform the installation commands again to update to the latest version.
Troubleshooting
The LocalStack CLI 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’sPATH
variable (in order to tell them where to find programs installed viapip
).- 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
- If you are using Windows, you can enable the
The
localstack
CLI is not starting the LocalStack containerIf you are using the
localstack
CLI to start LocalStack, but the container is not starting, please check the following:- Uncheck the Use kernel networking for UDP option in Docker Desktop (Settings → Resources → Network) or follow the steps in our documentation to disable it.
- Start LocalStack with a specific DNS address:
$ DNS_ADDRESS=0 localstack start
- Remove port 53 as indicated in our standard
docker-compose.yml
file.
How should I access the LocalStack logs on my local machine?
You can now avail logging output and error reporting using LocalStack logs. To access the logs, run the following command:
$ localstack logs
AWS requests are now logged uniformly in the INFO log level (set by default or when
DEBUG=0
). -The shape isAWS <service>.<operation> => <http-status> (<error type>)
. -Requests to HTTP endpoints are logged in a similar way:2022-09-12T10:39:21.165 INFO --- [ asgi_gw_0] localstack.request.aws : AWS s3.ListBuckets => 200 -2022-09-12T10:39:41.315 INFO --- [ asgi_gw_0] localstack.request.aws : AWS s3.CreateBucket => 200 -2022-09-12T10:40:04.662 INFO --- [ asgi_gw_0] localstack.request.aws : AWS s3.PutObject => 200 -2022-09-12T11:01:55.799 INFO --- [ asgi_gw_0] localstack.request.http : GET / => 200 -
How should I share the LocalStack logs to discover issues?
You can now share the LocalStack logs with us to help us discover issues. -To share the logs, run our diagnostic endpoint:
$ curl -s localhost:4566/_localstack/diagnose | gzip -cf > diagnose.json.gz
Ensure that the diagnostic endpoint is run after you have tried reproducing the affected task. -After running the task, run the diagnostic endpoint and share the archive file with your team members or LocalStack Support.
My application cannot reach LocalStack over the network
We have extensive network troubleshooting documentation available. -If this does not solve your problem then please reach out for help and support.
What’s next?
Now that you have LocalStack up and running, the following resources might be useful for your next steps:
- Check out our Quickstart guide if you are a new user to get started with LocalStack quickly.
- 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!
- Use
- 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.