sam build
This page provides reference information for the Amazon Serverless Application Model Command Line Interface (Amazon SAM CLI)
sam build
command.
-
For an introduction to the Amazon SAM CLI, see What is the Amazon SAM CLI?.
-
For documentation on using the Amazon SAM CLI
sam build
command, see Using sam build.
The sam build
command prepares an application for subsequent steps in the developer workflow, such as
local testing or deploying to the Amazon Web Services Cloud.
Usage
$
sam build
<arguments>
<options>
Arguments
- Resource ID
-
Optional. Instructs Amazon SAM to build a single resource declared in an Amazon SAM template. The build artifacts for the specified resource will be the only ones available for subsequent commands in the workflow, i.e.
sam package
andsam deploy
.
Options
--base-dir, -s
DIRECTORY
-
Resolves relative paths to the function's or layer's source code with respect to this directory. Use this option if you want to change how relative paths to source code folders are resolved. By default, relative paths are resolved with respect to the Amazon SAM template's location.
In addition to the resources in the root application or stack you are building, this option also applies nested applications or stacks.
This option applies to the following resource types and properties:
-
Resource type:
AWS::Serverless::Function
Property:CodeUri
-
Resource type:
AWS::Serverless::Function
Resource attribute:Metadata
Entry:DockerContext
-
Resource type:
AWS::Serverless::LayerVersion
Property:ContentUri
-
Resource type:
AWS::Lambda::Function
Property:Code
-
Resource type:
AWS::Lambda::LayerVersion
Property:Content
-
--beta-features | --no-beta-features
-
Allow or deny beta features.
--build-dir, -b
DIRECTORY
-
The path to a directory where the built artifacts are stored. This directory and all of its content are removed with this option.
--build-image
TEXT
-
The URI of the container image that you want to pull for the build. By default, Amazon SAM pulls the container image from Amazon ECR Public. Use this option to pull the image from another location.
You can specify this option multiple times. Each instance of this option can take either a string or a key-value pair. If you specify a string, it is the URI of the container image to use for all resources in your application. For example,
sam build --use-container --build-image amazon/aws-sam-cli-build-image-python3.8
. If you specify a key-value pair, the key is the resource name, and the value is the URI of the container image to use for that resource. For examplesam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.8
. With key-value pairs, you can specify different container images for different resources.This option only applies if the
--use-container
option is specified, otherwise an error will result. --build-in-source | --no-build-in-source
-
Provide
--build-in-source
to build your project directly in the source folder.The
--build-in-source
option supports the following runtimes and build methods:-
Runtimes – Any Node.js runtime supported by the
sam init --runtime
option. -
Build methods –
Makefile
,esbuild
.
The
--build-in-source
option is not compatible with the following options:-
--hook-name
-
--use-container
Default:
--no-build-in-source
-
--cached | --no-cached
-
Enable or disable cached builds. Use this option to reuse build artifacts that haven't changed from previous builds. Amazon SAM evaluates whether you've changed any files in your project directory. By default, builds are not cached. If the
--no-cached
option is invoked, it overrides thecached = true
setting in samcofig.toml.Note
Amazon SAM doesn't evaluate whether you've changed third-party modules that your project depends on, where you haven't provided a specific version. For example, if your Python function includes a
requirements.txt
file with the entryrequests=1.x
, and the latest request module version changes from1.1
to1.2
, then Amazon SAM doesn't pull the latest version until you run a non-cached build. --cache-dir
-
The directory where the cache artifacts are stored when
--cached
is specified. The default cache directory is.aws-sam/cache
. --config-env
TEXT
-
The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see Amazon SAM CLI configuration file.
--config-file
PATH
-
The path and file name of the configuration file containing default parameter values to use. The default value is "
samconfig.toml
" in the root of the project directory. For more information about configuration files, see Amazon SAM CLI configuration file. --container-env-var, -e
TEXT
-
Environment variables to pass to the build container. You can specify this option multiple times. Each instance of this option takes a key-value pair, where the key is the resource and environment variable, and the value is the environment variable's value. For example:
--container-env-var Function1.GITHUB_TOKEN=TOKEN1 --container-env-var Function2.GITHUB_TOKEN=TOKEN2
.This option only applies if the
--use-container
option is specified, otherwise an error will result. --container-env-var-file, -ef
PATH
-
The path and file name of a JSON file that contains values for the container's environment variables. For more information about container environment variable files, see Container environment variable file.
This option only applies if the
--use-container
option is specified, otherwise an error will result. --debug
-
Turns on debug logging to print debug messages that the Amazon SAM CLI generates, and to display timestamps.
--docker-network
TEXT
-
Specifies the name or ID of an existing Docker network that Lambda Docker containers should connect to, along with the default bridge network. If not specified, the Lambda containers connect only to the default bridge Docker network.
--exclude, -x
-
The Name of the resource(s) to exclude from the
sam build
. For example, if your template containsFunction1
,Function2
, andFunction3
and you runsam build --exclude Function2
, onlyFunction1
andFunction3
will be built. --help
-
Shows this message and exits.
--hook-name
TEXT
-
The name of the hook that is used to extend Amazon SAM CLI functionality.
Accepted values:
terraform
. --manifest , -m
PATH
-
The path to a custom dependency manifest file (for example, package.json) to use instead of the default.
--parallel
-
Enabled parallel builds. Use this option to build your Amazon SAM template's functions and layers in parallel. By default, the functions and layers are built in sequence.
--parameter-overrides
-
(Optional) A string that contains Amazon CloudFormation parameter overrides encoded as key-value pairs. Uses the same format as the Amazon Command Line Interface (Amazon CLI). For example: '
ParameterKey
=KeyPairName
,ParameterValue
=MyKey
ParameterKey
=InstanceType
,ParameterValue
=t1.micro
'. This option is not compatible with--hook-name
. --profile
TEXT
-
The specific profile from your credential file that gets Amazon credentials.
--region
TEXT
-
The Amazon Web Services Region to deploy to. For example, us-east-1.
--save-params
-
Save the parameters that you provide at the command line to the Amazon SAM configuration file.
--skip-prepare-infra
-
Skips the preparation stage if no infrastructure changes have been made. Use with the
--hook-name
option. --skip-pull-image
-
Specifies whether the command should skip pulling down the latest Docker image for the Lambda runtime.
--template-file, --template, -t
PATH
-
The path and file name of Amazon SAM template file
[default: template.[yaml|yml]]
. This option is not compatible with--hook-name
. --terraform-project-root-path
-
The relative or absolute path to the top-level directory containing your Terraform configuration files or function source code. If these files are located outside of the directory containing your Terraform root module, use this option to specify its absolute or relative path. This option requires that
--hook-name
be set toterraform
. --use-container
,-u
-
If your functions depend on packages that have natively compiled dependencies, use this option to build your function inside a Lambda-like Docker container.