Published on

Running AWS SAM with Podman Instead of Docker

Share post on:facebookFacebooklinkedinLinkedinthreadsThreads
Authors
  • avatar
    Name
    Edwin Popham
    Twitter

Like many engineers, I love the flexibility the AWS SAM CLI gives me when spinning up local Lambda environments. But there’s a catch—it’s built with Docker in mind, and Docker Desktop recently moved to a premium pricing model on macOS and Windows. That’s not ideal if you’re trying to save costs or stick with open source tooling.

dev using podman with aws sam

As someone who works half the week from my quiet home office in Ipswich and the other half commuting into Brisbane, I’m always looking for ways to simplify my development environment. Podman feels like a natural replacement—open source, daemonless, and more lightweight. The challenge? Getting SAM to use it properly.

The Problem: SAM Loves Docker

AWS SAM essentially delegates all its local emulation to Docker. When you run sam local invoke or sam local start-api, behind the scenes it spins up Docker containers for your Lambda functions. On macOS especially, this is tightly coupled with Docker Desktop.

If you drop Docker and install Podman, SAM is not officially aware of it. You’ll run into errors because Podman doesn’t provide the same Docker socket that SAM expects. Out of the box, sam local just doesn’t know Podman exists.

Step-by-Step Guide: Using AWS SAM with Podman on macOS

For those keen to ditch Docker Desktop and try Podman, here’s a step-by-step on how to get it working:

1. Install Podman

Use Homebrew to install Podman on macOS:

brew install podman

Once installed, you can verify by running:

podman --version

2. Start the Podman Machine

Podman on macOS runs inside a lightweight virtual machine to emulate Linux containers:

podman machine init
podman machine start

Confirm the VM is running with:

podman machine list

3. Create a Docker Alias Pointing to Podman

Since AWS SAM looks explicitly for the docker command, create an alias to trick SAM into using Podman’s Docker-compatible CLI:

alias docker=podman

To make this permanent, add the above line to your shell profile, e.g., ~/.zshrc or ~/.bash_profile.

4. Configure SAM Template for ARM64 Architecture

Podman on macOS tends to work reliably with ARM64 containers, especially on Apple Silicon Macs. In your SAM template file (template.yaml), add the architecture override:

Resources:
  YourFunction:
    Type: AWS::Serverless::Function
    Properties:
      Architectures:
        - arm64
      # other properties here

This forces SAM and Podman to run the ARM64 variant of your Lambda containers locally.

5. Run SAM CLI Commands

You should now be able to invoke your function locally:

sam build
sam local invoke YourFunction

Or start the API locally:

sam local start-api

If you see errors, double-check your alias is active in your terminal session, and that the Podman machine is running.

6. Deploy to AWS as Usual (Remember to Switch Architecture)

When deploying to AWS, it’s important to switch your architecture back to x86_64 in your SAM template if that is the architecture you want your Lambda functions to run on in the cloud. The ARM64 setting is just a local workaround for Podman on macOS, but AWS Lambdas commonly run on x86_64.

Update your template like this before deployment:

Architectures:
  - x86_64

You might maintain separate SAM templates, use build scripts that swap the architecture, or configure your CI/CD pipeline to handle this switch. Failing to do this means your deployed Lambda could run on ARM64, which might not be your intended target.

The Trade-Offs

The main inconvenience is the dual arch setup — ARM64 for local testing with Podman, and x86_64 for AWS deployment. It’s manageable but definitely not seamless. However, this workaround saves the cost and headache of Docker Desktop’s licensing changes.

Why Bother With Podman?

  • Cost saving: Docker Desktop now has licensing considerations if you’re using it for work. Podman is free and open source.
  • Closer to Linux-native feel: Podman doesn’t require a central daemon like Docker, which is refreshing if you’ve ever wrestled with the Docker service hanging.
  • Lightweight: It just feels snappier, especially on a developer machine already running plenty of background services.

For me, moving to Podman also felt like leaning into open source values—a bit like backing a local rugby league side instead of the flashy Sydney clubs. It just feels right.

What’s Next?

I’d love to see AWS SAM officially support Podman, or at least provide better documentation for non-Docker runtimes. Until then, I’ll keep refining my setup. For the moment:

  • Using alias docker=podman works well enough.
  • Forcing arm64 in SAM templates is a trade-off.
  • Deployment to AWS still goes off without a hitch because CloudFormation takes care of running the function on x86_64.

So yes, Podman can run SAM workloads—it just takes a bit of tweaking. For me, it’s worth the small hassle to avoid Docker Desktop’s premium gatekeeping.

If anyone else has tricks for improving this workflow or has tested other alternatives, I’d love to hear about it in the comments.

Share post on:facebookFacebooklinkedinLinkedinthreadsThreads