AWS Serverless Application Model
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Installing the AWS SAM CLI on macOS

The following steps help you to install and configure the required prerequisites for using the AWS SAM CLI on your macOS host:

  1. Create an AWS account.

  2. Configure IAM permissions.

  3. Install the AWS CLI.

  4. Create an Amazon S3 bucket.

  5. Install Docker. Note: Docker is only a prerequisite for testing your application locally.

  6. Install Homebrew.

  7. Install the AWS SAM CLI.

Step 1: Create an AWS Account

If you don't already have an AWS account, see and choose Create an AWS Account. For detailed instructions, see Create and Activate an AWS Account.

Step 2: Create an IAM User with Administrator Permissions

If you don't already have an IAM user with administrator permissions, see Creating Your First IAM Admin User and Group in the IAM User Guide.

Step 3: Install and Configure the AWS CLI

If you don't already have the AWS CLI installed, this step shows you how install and configure it. You can check whether you have the AWS CLI installed by executing aws --version at a command line.

This section has two substeps: a) Install the AWS CLI using a bundled installer, and b) Configure the AWS CLI to use your credentials, default AWS Region, and desired output format.

Step 3a: Install the AWS CLI

We recommend that you use a bundled installer to avoid issues with existing Python installations when you have multiple versions.

The following commands assume that you want to install the AWS CLI for all users of a development host using sudo, and that the system default version of Python should be used. For alternative installation options, see Installing the AWS CLI.

curl "" -o "" unzip sudo ./awscli-bundle/install -i /usr/local/aws -b /usr/local/bin/aws

You should see the following output as the last line of a successful installation:

 You can now run: /usr/local/bin/aws --version

Step 3b: Configure the AWS CLI

After you've verified installing the AWS CLI, you can configure it with your credentials, default AWS Region, and desired output format. To do this, you first create the necessary access keys by following these steps:

  1. Sign in to the AWS Management Console and open the IAM console at

  2. In the navigation pane, choose Users.

  3. Choose the name of the user whose access keys you want to create, and then choose the Security credentials tab.

  4. In the Access keys section, choose Create access key.

  5. To view the new access key pair, choose Show. You will not have access to the secret access key again after this dialog box closes. Your credentials will look something like this:


    • Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

  6. To download the key pair, choose Download .csv file. Store the keys in a secure location. You will not have access to the secret access key again after this dialog box closes.

    Keep the keys confidential in order to protect your AWS account and never email them. Do not share them outside your organization, even if an inquiry appears to come from AWS or No one who legitimately represents Amazon will ever ask you for your secret key.

  7. After you download the .csv file, choose Close. When you create an access key, the key pair is active by default, and you can use the pair right away.

Configure the AWS CLI with your using the access keys you just created by executing the following command:

aws configure

When you're prompted, replace the following examples with your access keys:

 AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE                         # Enter your access key
 AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY # Enter your secret key
 Default region name [None]: us-east-1                                  # Example regions: us-east-1, ap-east-1, eu-central-1, sa-east-1
 Default output format [None]: json                                     # Or 'text'

Additional configuration options are available in configuring the AWS CLI.

Step 4: Create an Amazon S3 Bucket

AWS SAM uses an Amazon S3 bucket in your AWS account as a repository to store deployment artifacts. To use the package and deployment functionality of AWS SAM, you must have an Amazon S3 bucket in the Region that you're working in.

If you need to create an Amazon S3 bucket, you can run the following command:

aws s3 mb s3://bucketname --region region # Example regions: us-east-1, ap-east-1, eu-central-1, sa-east-1

You should see the following output for a successfully created Amazon S3 bucket:

 make_bucket: bucketname

Remember to keep track of your Amazon S3 bucket name, because you need it to package your serverless application.

Step 5: Install Docker


Docker is only a prerequisite for testing your application locally and to build deployment packages using the --use-container flag. You may skip this section or install Docker at a later time if you do not plan to use these features initially.

Docker is an application that runs containers on your macOS machines. AWS SAM provides a local environment that's similar to AWS Lambda to use as a Docker container. You can use this container to build, test, and debug your serverless applications.

You must have Docker installed and working to be able to run serverless projects and functions locally with the AWS SAM CLI. The AWS SAM CLI uses the DOCKER_HOST environment variable to contact the Docker daemon. The following steps describe how to install, configure, and verify a Docker installation to work with the AWS SAM CLI.

  1. Install Docker

    The AWS SAM CLI supports Docker running on macOS Sierra 10.12 or above. To install Docker see Install Docker Desktop for Mac.

  2. Configure your shared drives

    The AWS SAM CLI requires that the project directory, or any parent directory, is listed in a shared drive. To share drives on macOS, see File sharing.

  3. Verify the installation

    After Docker is installed, verify that it's working. Also confirm that you can run Docker commands from the AWS SAM CLI (for example, docker ps). You don't need to install, fetch, or pull any containers––the AWS SAM CLI does this automatically as required.

If you run into issues installing Docker, see the Docker installation guide for troubleshooting tips.

Step 6: Install Homebrew

The recommended approach for installing the AWS SAM CLI on macOS is to use the Homebrew package manager. For more information about Homebrew, see Homebrew Documentation.

To install Homebrew, run the following and follow the prompts:

/usr/bin/ruby -e "$(curl -fsSL"

Verify that Homebrew is installed:

brew --version

You should see output like the following on successful installation of Homebrew:

 Homebrew 2.1.6 
 Homebrew/homebrew-core (git revision ef21; last commit 2019-06-19)

Step 7: Install the AWS SAM CLI

Follow these steps to install the AWS SAM CLI using Homebrew:

brew tap aws/tap brew install aws-sam-cli

Verify the installation:

sam --version

You should see output like the following after successful installation of the AWS SAM CLI:

 SAM CLI, version 0.19.0

You're now ready to start development.

Next Steps

You're now ready to begin building your own serverless applications using AWS SAM! If you want to start with sample serverless applications, choose one of the following links: