A Guide to Installing and Starting LocalStack on Windows 11, macOS, and Chromebook Linux

-

 

A Guide to Installing and Starting LocalStack on Windows 11, macOS, and Chromebook Linux

#aws#localstack#cloud#infrastructureascode





This guide will walk you through the process of installing and starting LocalStack, the AWS local emulator, on three different platforms. The installation requires Docker to be running in the background and will use the LocalStack CLI to manage everything from your terminal.

Before you begin, it's considered a best practice to set up a Python virtual environment to keep your project's dependencies isolated from your system's global Python packages.

A note on troubleshooting: This guide focuses on the standard installation path. If you encounter specific error messages along the way (such as missing Python packages or dependencies), they're usually descriptive enough to troubleshoot with your preferred AI assistant or search engine.

Network note: LocalStack uses port 4566 by default. Ensure this port isn't blocked by your firewall or already in use by another application.

Getting Started: Prerequisites and Setup

Step 1: From your home directory, create a central directory for all your virtual environments. You only need to do this step once.

mkdir envs

Step 2: Navigate into this new directory and create a new project directory within it. Then, move into your new project directory.

cd envs
mkdir localstack-lab
cd localstack-lab

Step 3: Now, create and activate the virtual environment for your project.

python3 -m venv venv
source venv/bin/activate

Success indicator: Your command prompt should now be prefixed with (venv), indicating the virtual environment is active.

Before activation:

$

After activation:

(venv) $

Once your virtual environment is active, you can proceed with the installation for your specific operating system.

1. Windows 11 (using WSL)

The best way to use LocalStack on Windows 11 is with the Windows Subsystem for Linux (WSL).

Step 1: If you haven't already, open PowerShell or Command Prompt as an administrator and run:

wsl --install

This will install WSL and a default Linux distribution like Ubuntu. After a restart, you'll be able to launch the Linux environment.

Note: If this command fails, you may need to enable virtualization in your BIOS settings. Some systems require this feature to be manually enabled.

Step 2: Ensure you have Docker Desktop installed on Windows and configured to use the WSL 2 backend. Launch Docker Desktop and verify it's running (you should see a green "running" indicator in the bottom-left corner).

Step 3: From within your WSL terminal, with your virtual environment active, run the following command to install the LocalStack CLI:

python3 -m pip install --upgrade localstack

Success indicator: The installation should complete without errors and you can verify by running localstack --version.

Step 4: Verify Docker is accessible from WSL by running:

docker ps

If this returns a list of containers (even if empty), you're ready to proceed.

Note: If you see a "permission denied" error, you may need to add your user to the docker group or ensure Docker Desktop integration with WSL is enabled in Docker Desktop settings.

Step 5: Now, start LocalStack with the following command:

localstack start

2. macOS (using Terminal)

The process on macOS is very similar to a standard Linux installation.

Step 1: Download and install Docker Desktop for Mac from the official Docker website. Launch Docker Desktop and verify it's running (look for the whale icon in your menu bar).

Step 2: Open your Terminal app, navigate to your project directory, activate your virtual environment, and run the following command to install the LocalStack CLI:

python3 -m pip install --upgrade localstack

Success indicator: The installation should complete without errors and you can verify by running localstack --version.

Step 3: Verify Docker is running by executing:

docker ps

You should see a table of containers (even if empty). If you see an error about Docker not running, make sure Docker Desktop is fully started.

Step 4: With Docker Desktop running in the background, start LocalStack from your terminal:

localstack start

3. Chromebook (using Linux)

Chromebooks with Linux (Beta) enabled provide a Debian-based environment.

Step 1: First, make sure you have Docker installed. Open your Linux terminal and run these commands:

# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

Step 2: Add your user to the docker group to run Docker without sudo:

sudo usermod -aG docker $USER

You'll need to log out and back in for this to take effect.

Step 3: Open your Chromebook's Linux terminal, navigate to your project directory, activate your virtual environment, and run the following command to install the LocalStack CLI:

python3 -m pip install --upgrade localstack

Success indicator: The installation should complete without errors and you can verify by running localstack --version.

Step 4: Ensure the Docker daemon is running:

sudo systemctl start docker
docker ps

Step 5: Start LocalStack with the following command:

localstack start

Starting and Stopping LocalStack

Once LocalStack is running, you will see output in your terminal indicating that the server is up and ready. The terminal will remain occupied while LocalStack is running, displaying log information.

Typical LocalStack Startup Output

Starting local dev environment. CTRL-C to quit.
     __                     _______ __             __  
    / /   ____  _________ _/ / ___// /_____ ______/ /__
   / /   / __ \/ ___/ __ `/ /\__ \/ __/ __ `/ ___/ //_/
  / /___/ /_/ / /__/ /_/ / /___/ / /_/ /_/ / /__/ ,<   
 /_____/\____/\___/\__,_/_//____/\__/\__,_/\___/_/|_|  

 💻 LocalStack CLI 3.4.0
 👤 Profile: default

[...]
Ready.

Success indicator: When you see "Ready." at the bottom of the output, LocalStack is fully started and listening for requests.

Testing LocalStack with a Real Workflow

Now let's verify LocalStack works by running a simple smoke test. This will demonstrate the typical two-terminal workflow you'll use when developing with LocalStack.

Why two terminals? Terminal 1 is actively running the LocalStack server and displaying its logs - it's occupied. Terminal 2 is your workspace for sending commands to that server. You'll see your commands in Terminal 2 and the corresponding server logs in Terminal 1.

Terminal 2: Setting Up and Running the Smoke Test

Open a second terminal window and run the following commands:

# Navigate to your project directory
cd ~/envs/localstack-lab

# Activate the virtual environment
source venv/bin/activate

# Install AWS CLI in the virtual environment
pip install awscli

# Create a test S3 bucket
aws --endpoint-url=http://localhost:4566 s3 mb s3://test-bucket

# List all S3 buckets to verify
aws --endpoint-url=http://localhost:4566 s3 ls

Terminal 2 Output:

(venv) $ aws --endpoint-url=http://localhost:4566 s3 mb s3://test-bucket
make_bucket: test-bucket

(venv) $ aws --endpoint-url=http://localhost:4566 s3 ls
2025-10-11 14:32:15 test-bucket

Terminal 1: Observing the Server Logs

While you run commands in Terminal 2, switch back to Terminal 1 (where LocalStack is running) and you'll see log entries appear showing the S3 API calls being processed:

Terminal 1 Output:

2025-10-11T14:32:15.234  INFO --- [   asgi_gw_0] localstack.request.aws     : AWS s3.CreateBucket => 200
2025-10-11T14:32:18.567  INFO --- [   asgi_gw_0] localstack.request.aws     : AWS s3.ListBuckets => 200

Success! You've just created and listed an S3 bucket entirely on your local machine. This confirms LocalStack is working correctly and responding to AWS API calls.

Shutting Down

Now that you've verified everything works, let's clean up both terminals properly.

In Terminal 2, deactivate the virtual environment and close the terminal:

deactivate
exit

In Terminal 1, press Ctrl+C to gracefully stop the LocalStack server. After LocalStack shuts down, you'll be returned to the command prompt (still inside the virtual environment). Clean up with:

deactivate
cd

Your prompt should no longer show the (venv) prefix, and you'll be back in your home directory.

Getting Back to Work Later

When you want to use LocalStack again in a future session, you'll need to reactivate your virtual environment and restart LocalStack:

cd ~/envs/localstack-lab
source venv/bin/activate
localstack start

Remember to have Docker Desktop running before starting LocalStack.

Next steps: With LocalStack running, you can now use the AWS CLI with the --endpoint-url=http://localhost:4566 flag to interact with local AWS services without incurring cloud costs. Happy developing!

Aaron Rose is a software engineer and technology writer at tech-reader.blog and the author of Think Like a Genius.

Comments

Post a Comment

Popular posts from this blog

The New ChatGPT Reason Feature: What It Is and Why You Should Use It

-
Image
The New ChatGPT Reason Feature: What It Is and Why You Should Use It Offers More Than Just a Simple Answer ChatGPT continues to evolve, constantly introducing new features that make user interactions more tailored and insightful. One of the latest additions is the Reason option, which you can access through the slash menu. At its core, this feature gives you more control over the depth of responses, specifically when you’re looking for more than just a simple answer. In this article, we’ll explore what the Reason feature is, where it originated, why it matters, and how you can make the most of it. What Is the Reason Feature? The Reason option prompts ChatGPT to provide a detailed, structured explanation that dives into the reasoning behind an answer. It focuses on giving a logical breakdown of how the conclusion was reached, rather than just providing a surface-level response. Essentially, it’s a way of saying, "I want to understand not just the answer, but the reasoning behind it...
Read more

Raspberry Pi Connect vs. RealVNC: A Comprehensive Comparison

-
Image
Raspberry Pi Connect vs. RealVNC:  A  Comprehensive Comparison The Raspberry Pi has revolutionized the way we interact with computers, providing a low-cost, highly adaptable platform for countless applications. One critical aspect of using a Raspberry Pi, especially for remote management and control, is the ability to access it from another device. Historically, RealVNC has been the go-to solution for this purpose. However, the recent introduction of Raspberry Pi Connect offers an integrated alternative. This article will compare Raspberry Pi Connect and RealVNC, exploring their features, requirements, and practical applications. Introduction to Raspberry Pi Connect Raspberry Pi Connect is a new VNC service directly integrated into Raspberry Pi OS 12. Designed for simplicity and ease of use, Connect aims to provide a seamless remote desktop experience for Raspberry Pi users. Currently in beta, Raspberry Pi Connect is free to use and requires a Raspberry Pi 4, 400, or 5 running...
Read more

Insight: The Great Minimal OS Showdown—DietPi vs Raspberry Pi OS Lite

-
Image
Insight: The Great Minimal OS Showdown—DietPi vs Raspberry Pi OS Lite When you're building a headless server, IoT device, or lightweight project box, the last thing you want is bloatware eating your precious resources. Enter the world of minimal operating systems—where every megabyte matters and efficiency reigns supreme. Two contenders dominate this space: DietPi and Raspberry Pi OS Lite. Both promise lean, mean computing machines that boot straight to the command line. But scratch beneath the surface, and you'll find they take fundamentally different approaches to the "less is more" philosophy. The Minimalist's Dilemma Picture this: You've got a Raspberry Pi 3B+ sitting on your desk, destined to become a home media server. Do you go with the familiar comfort of Raspberry Pi OS Lite, or venture into DietPi's optimized territory? The choice isn't just about personal preference—it's about understanding what "minimal" means to each operatin...
Read more