How to install LocalStack (AWS cloud service emulator) on WSL2 to develop cloud and serverless apps offline?

· 5 min read
LocalStack (AWS cloud service emulator)

LocalStack is an AWS cloud service emulator that can be used as a local cloud sandbox for development, prototyping and testing. It is "A fully functional local cloud stack". You can efficiently build AWS cloud and serverless applications locally without connecting to AWS cloud. Therefore, it will help to accelerate your workflow and productivity without any surprise in AWS billing.

In this post, I'll use Ubuntu 22.04 distro (jammy) running on WSL2 (Windows Subsystem for Linux) to install LocalStack. Multiple installation options are available, but I'll show my preferred one, LocalStack CLI - simplest to start and manage LocalStack.

abhijit@AwsJunkie:~$ uname -a
Linux AwsJunkie #1 SMP Wed Mar 2 00:30:59 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux

abhijit@AwsJunkie:~$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 22.04.1 LTS
Release:        22.04
Codename:       jammy


  • python3:
  • pip (package installer for Python)
  • docker

python3 or pip may not come pre-installed by default. In my case, Python3 came preinstalled for Ubuntu 22 distro.

abhijit@AwsJunkie:~$ python3 --version
Python 3.10.6

Otherwise, install python3 and/or pip.

abhijit@AwsJunkie:~$ sudo apt update -y && sudo apt upgrade -y
abhijit@AwsJunkie:~$ sudo apt install python3 python3-pip -y
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
python3 is already the newest version (3.10.6-1~22.04).
python3 set to manually installed.
The following additional packages will be installed:
0 upgraded, 68 newly installed, 0 to remove and 0 not upgraded.
Need to get 72.1 MB of archives.
After this operation, 242 MB of additional disk space will be used.
Get:1 jammy-updates/main amd64 libc-dev-bin amd64 2.35-0ubuntu3.1 [20.4 kB]
Get:2 jammy-updates/main amd64 linux-libc-dev amd64 5.15.0-69.76 [1326 kB]
Setting up build-essential (12.9ubuntu3) ...
Setting up libpython3-dev:amd64 (3.10.6-1~22.04) ...
Setting up python3-dev (3.10.6-1~22.04) ...
Processing triggers for man-db (2.10.2-1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.1) ...

Check docker version to confirm Docker is installed or not.

abhijit@AwsJunkie:~$ docker version
Client: Docker Engine - Community
 Version:           23.0.1
 API version:       1.42
 Go version:        go1.19.5
 Git commit:        a5ee5b1
 Built:             Thu Feb  9 19:47:01 2023
 OS/Arch:           linux/amd64
 Context:           default

For Docker installation, refer the below article.

Install Docker Engine and Docker Compose on Windows Subsystem for Linux (WSL 2)
If you already have Docker Desktop installed or want to use docker on both Windows and WSL2, then Docker Desktop is better choice. But I personally prefer to install and run the “most-loved Tool” docker inside Windows Subsystem for Linux (WSL 2). This keeps the development environment isolated and…

Install LocalStack CLI

To install LocalStack CLI, run pip install localstack without using sudo or root user. "LocalStack must be installed and started entirely under a local non-root user."

abhijit@AwsJunkie:~$ pip install localstack
Defaulting to user installation because normal site-packages is not writeable
Collecting localstack
  Downloading localstack-1.4.0-py3-none-any.whl (1.3 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.3/1.3 MB 2.7 MB/s eta 0:00:00
Successfully installed apispec-6.3.0 boto3-1.26.100 botocore-1.29.100 cachetools-5.0.0 certifi-2022.12.7 charset-normalizer-3.1.0 click-8.1.3 dill-0.3.2 dnslib-0.9.23 dnspython-2.3.0 ecdsa-0.18.0 idna-3.4 jmespath-1.0.1 localstack-1.4.0 localstack-client-2.0 localstack-ext-1.4.0 markdown-it-py-2.2.0 mdurl-0.1.2 packaging-23.0 pbr-5.11.1 plux-1.3.1 psutil-5.9.4 pyaes-1.6.1 pyasn1-0.4.8 pygments-2.14.0 python-dateutil-2.8.2 python-dotenv-1.0.0 python-jose-3.3.0 requests-2.28.2 rich-13.3.3 rsa-4.9 s3transfer-0.6.0 semver-2.13.0 stevedore-5.0.0 tabulate-0.9.0 tailer-0.4.1 urllib3-1.26.15

Reload the current shell.

abhijit@AwsJunkie:~$ localstack
localstack: command not found
abhijit@AwsJunkie:~$ sudo nano ~/.profile

Verify LocalStack CLI installation

Check version to confirm whether installation is successful or not.

abhijit@AwsJunkie:~$ localstack --version
abhijit@AwsJunkie:~$ localstack --help
Usage: localstack [OPTIONS] COMMAND [ARGS]...

  The LocalStack Command Line Interface (CLI)

  --version       Show the version and exit.
  --debug         Enable CLI debugging mode
  --profile TEXT  Set the configuration profile
  --help          Show this message and exit.

  config  Inspect your LocalStack configuration
  infra   Manipulate LocalStack infrastructure (legacy)
  login   Log in with your account credentials
  logs    Show the logs of the LocalStack container
  pod     Manage the state of your instance via Cloud Pods
  ssh     Obtain a shell in the running LocalStack container
  start   Start LocalStack
  status  Print status information about the LocalStack runtime
  stop    Stop the running LocalStack container
  update  Update LocalStack components
  wait    Wait on the LocalStack container to start

LocalStack "must be started entirely under a local non-root user". But Docker daemon runs as the root user. Therefore, LocalStack  will not be able to access Unix socket created by Docker daemon. To address this, create a Unix group called docker (if not created during Docker Engine installation) and add the user to that group.

abhijit@AwsJunkie:~$ sudo groupadd docker
groupadd: group 'docker' already exists
abhijit@AwsJunkie:~$ sudo usermod -aG docker $USER

Logout and re-login. And run newgrp docker to activate the changes to groups.

abhijit@AwsJunkie:~$ newgrp docker

Finally, start the LocalStack docker container. Use -d or --detached option to start LocalStack in the background.

abhijit@AwsJunkie:~$ localstack start -d

     __                     _______ __             __
    / /   ____  _________ _/ / ___// /_____ ______/ /__
   / /   / __ \/ ___/ __ `/ /\__ \/ __/ __ `/ ___/ //_/
  / /___/ /_/ / /__/ /_/ / /___/ / /_/ /_/ / /__/ ,<

 💻 LocalStack CLI 1.4.0

[20:52:41] starting LocalStack in Docker mode 🐳                                             
           preparing environment                                                              
           configuring container                                                              
           starting container                                                                 
[20:53:03] detaching

Check AWS services loaded by localstack and available for you to start building awesome AWS cloud application in your local machine. AWS Service Feature Coverage is more in Pro version than Community edition.

abhijit@AwsJunkie:~$ curl -s http://localhost:4566/health | json_pp
   "services" : {
      "acm" : "available",
      "apigateway" : "available",
      "cloudformation" : "available",
      "cloudwatch" : "available",
      "config" : "available",
      "dynamodb" : "available",
      "dynamodbstreams" : "available",
      "ec2" : "available",
      "es" : "available",
      "events" : "available",
      "firehose" : "available",
      "iam" : "available",
      "kinesis" : "available",
      "kms" : "available",
      "lambda" : "available",
      "logs" : "available",
      "opensearch" : "available",
      "redshift" : "available",
      "resource-groups" : "available",
      "resourcegroupstaggingapi" : "available",
      "route53" : "available",
      "route53resolver" : "available",
      "s3" : "available",
      "s3control" : "available",
      "secretsmanager" : "available",
      "ses" : "available",
      "sns" : "available",
      "sqs" : "available",
      "ssm" : "available",
      "stepfunctions" : "available",
      "sts" : "available",
      "support" : "available",
      "swf" : "available",
      "transcribe" : "available"
   "version" : ""