AWS SAM local – debugging Lambda and API Gateway with breakpoints demo


Chris Mckinnel



This new serverless world is great, but if you dive into it too fast – sometimes you end up getting caught up trying to get it all working, and forget to focus on having your local development environment running efficiently. This often costs developers time, and as a consequence it also costs the business money.

One of the things I see fairly often, is developers adopting AWS Serverless technologies because they know that’s what they should be doing (and everyone else is doing it), but they end up sacrificing their local development flows to do so – and the one that’s most obvious is running lambdas locally with breakpoints.

This post covers how to get local debugging working using breakpoints and an IDE from a fresh AWS SAM project using the Python3.6 runtime.

I’m using the Windows Subsystem for Linux and Docker on Windows.




Video Demo

There is a high level step-by-step below, but the video contains exact steps and a demo of this working using WSL and Docker for Windows.



Assuming you’ve got the prerequisites above, the process of getting a new project set up and hooked up to your IDE is relatively straight forward.

1. Initialise a new python runtime project with:

$ sam init --runtime python3.6

2. Test we can run our API Gateway mock, backed by our lambda locally using:

$ sam local start-api

3. Hit our app in a browser at:

4. Add the debugging library to requirements.txt


5. Import the debug library and have it listen on a debug port


import ptvsd

ptvsd.enable_attach(address=(‘’, 5890), redirect_output=True)

6. Build the changes to the app in a container using

$ sam build --use-container

7. Set a breakpoint in your IDE

8. Configure the debugger in your IDE (Visual Code uses launch.json)



While adopting new technologies can be challenging and fun, it’s important that you keep your local development as efficient as possible so you can spend your time on what you do best: developing.

Consegna helps its partners transition from traditional development processes, to cloud development processes with minimal disruption to workflow. By demonstrating to developers that their day-to-day lives won’t change as much as they think, we find that widespread adoption and enthusiasm for the cloud is the norm, not the exception for developers in our customer engagements.

To find out more, get in touch via the contact form below.