Build: Simulate S3 on Your Local Linux Machine with LocalStack

Simulate S3 on Your Local Linux Machine with LocalStack

When you're working with AWS S3, you're typically interacting with a remote cloud environment. But what if you want to test file uploads, downloads, and bucket permissions — all without touching the internet? That’s where LocalStack shines. It lets you spin up a local mock version of AWS, including services like S3, using nothing but your own Linux machine.

In this tutorial, everything happens locally: one machine, one terminal, and no cloud dependency. You'll create a bucket, upload a file, download it again, and confirm that it all works — just like it would on AWS.

Before you begin, make sure you’ve already installed LocalStack and set up a Python virtual environment. We’ll assume your virtual environment is named localstack-venv, as described in our earlier post. Follow this guide to install LocalStack on Debian-based Linux if you haven’t done that step yet.

Once the environment is ready, activate it: 

Bash

source ~/localstack-venv/bin/activate   

All commands in this tutorial will be run from within the virtual environment.

From here, we’ll start LocalStack, configure the AWS CLI, and create your first local S3 bucket.

1. Start LocalStack

Make sure LocalStack is running. You can start it like this: 

Bash

localstack start   

Wait for the terminal to show that services are up. You'll see a Ready. message in the termial.  You’re now running a local version of AWS.  Note that LocalStack is running in the foreground and will display log messages to your current terminal.  So to continue this tutorial, you'll start up a second Linux terminal to enter LocalStack commands.

2. Set Up Your AWS CLI for LocalStack

In a second Linux terminal, tell the AWS CLI to use test credentials and LocalStack’s local endpoint. Each line sets one environment variable, and you should enter them one at a time:

The access key ID is like your AWS login: 

Bash

export AWS_ACCESS_KEY_ID=test   

The secret access key is like your AWS password: 

Bash

export AWS_SECRET_ACCESS_KEY=test   

And the region determines the default service region: 

Bash

export AWS_DEFAULT_REGION=us-east-1   

These test credentials work only with LocalStack and are not linked to any real AWS account.

When using aws commands with LocalStack, you'll need to include the --endpoint-url flag to tell the CLI where to send requests. Here's an example of how to include it: 

Bash

aws s3 ls --endpoint-url=http://localhost:4566   

Alternatively, use awslocal, which includes the endpoint URL by default. For example, instead of writing: 

Bash

aws s3 ls --endpoint-url=http://localhost:4566   

You can simply run:

Bash

awslocal s3 ls   

This makes your commands shorter and easier to read.

3. Create an S3 Bucket

Now create a new bucket called my-local-bucket using the mb command, which stands for make bucket: 

Bash

awslocal s3 mb s3://my-local-bucket   

You’ll see a confirmation that the bucket was created.

4. Upload a File

Make a quick text file: 

Bash

echo "Hello, LocalStack!" > hello.txt   

Then upload it to the bucket: 

Bash

awslocal s3 cp hello.txt s3://my-local-bucket/   

Verify the upload using ls:

Bash

awslocal s3 ls s3://my-local-bucket/   

Expected output: 

Bash

2025-04-29 15:23:00 20 hello.txt   

5. Download the File

To verify, remove the file locally: 

Bash

rm hello.txt   

And re-download it. The final period . means the file will be downloaded to your current working directory: 

Bash

awslocal s3 cp s3://my-local-bucket/hello.txt .   

List the contents of your local directory to verify the download: 

Bash

ls -l   

Expected output: 

Bash

-rw-r--r-- 1 user user 20 Apr 29 15:25 hello.txt   

Check the contents of the file:

Bash

cat hello.txt   

You should see: 

Bash

Hello, LocalStack!  

6. Deactivate the Virtual Environment

When you're done, you can exit the virtual environment by running: 

Bash

deactivate   

This returns your shell to its original state.

Conclusion: You’re Now Simulating AWS on Your Own Terms

That’s your end-to-end S3 simulation, right on your Linux box — no SSH, no AWS, no cloud costs. Just a local dev playground that behaves like the real thing. From here, you can branch out into event-driven workflows, Lambda emulation, and more.

Need AWS Expertise?

We'd love to help you with your AWS projects.  Feel free to reach out to us at info@pacificw.com.

Written by Aaron Rose, software engineer and technology writer at Tech-Reader.blog.