# sam local start-lambda
<a name="sam-cli-command-reference-sam-local-start-lambda"></a>

This page provides reference information for the Amazon Serverless Application Model Command Line Interface (Amazon SAM CLI) `sam local start-lambda` subcommand.
+ For an introduction to the Amazon SAM CLI, see [What is the Amazon SAM CLI?](what-is-sam-overview.md#what-is-sam-cli)
+ For documentation on using the Amazon SAM CLI `sam local start-lambda` subcommand, see [Introduction to testing with sam local start-lambda](using-sam-cli-local-start-lambda.md).

The `sam local start-lambda` subcommand starts a local endpoint to emulate Amazon Lambda.

## Usage
<a name="ref-sam-cli-local-start-lambda-usage"></a>

```
$ sam local start-lambda <options>
```

## Options
<a name="ref-sam-cli-local-start-lambda-options"></a>

`--add-host LIST`  <a name="ref-sam-cli-local-start-lambda-options-add-host"></a>
Passes a hostname to IP address mapping to the Docker container's host file. This parameter can be passed multiple times.  

**Example**  
Example: `--add-host example.com:127.0.0.1`

`--beta-features | --no-beta-features`  <a name="ref-sam-cli-local-start-lambda-options-beta-features"></a>
Allow or deny beta features.

`--config-env TEXT`  <a name="ref-sam-cli-local-start-lambda-options-config-env"></a>
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](serverless-sam-cli-config.md).

`--config-file PATH`  <a name="ref-sam-cli-local-start-lambda-options-config-file"></a>
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](serverless-sam-cli-config.md).

`--container-env-vars`  <a name="ref-sam-cli-local-start-lambda-options-container-env-vars"></a>
Optional. Pass environment variables to image container when locally debugging.

`--container-host TEXT`  <a name="ref-sam-cli-local-start-lambda-options-container-host"></a>
Host of locally emulated Lambda container. The default value is `localhost`. If you want to run Amazon SAM CLI in a Docker container on macOS, you can specify `host.docker.internal`. If you want to run the container on a different host than Amazon SAM CLI, you can specify the IP address of the remote host.

`--container-host-interface TEXT`  <a name="ref-sam-cli-local-start-lambda-options-container-host-interface"></a>
The IP address of the host network interface that container ports should bind to. The default value is `127.0.0.1`. Use `0.0.0.0` to bind to all interfaces.

`--container-dns TEXT`  <a name="ref-sam-cli-local-start-lambda-options-container-dns"></a>
Specifies a custom DNS server for the Docker container. This parameter can be passed multiple times to specify multiple DNS servers.  

**Example**  
Example: `--container-dns 8.8.8.8`

`--debug`  <a name="ref-sam-cli-local-start-lambda-options-debug"></a>
Turns on debug logging to print debug message generated by the Amazon SAM CLI and display timestamps.

`--debug-args TEXT`  <a name="ref-sam-cli-local-start-lambda-options-debug-args"></a>
Additional arguments to be passed to the debugger.

`--debug-function`  <a name="ref-sam-cli-local-start-lambda-options-debug-function"></a>
Optional. Specifies the Lambda function to apply debug options to when `--warm-containers` is specified. This parameter applies to `--debug-port`, `--debugger-path`, and `--debug-args`.

`--debug-port, -d TEXT`  <a name="ref-sam-cli-local-start-lambda-options-debug-port"></a>
When specified, starts the Lambda function container in debug mode, and exposes this port on the local host.

`--debugger-path TEXT`  <a name="ref-sam-cli-local-start-lambda-options-debugger-path"></a>
The host path to a debugger to be mounted into the Lambda container.

`--docker-network TEXT`  <a name="ref-sam-cli-local-start-lambda-options-docker-network"></a>
The name or ID of an existing Docker network that Lambda Docker containers should connect to, along with the default bridge network. If this is specified, the Lambda containers only connect to the default bridge Docker network.

`--docker-volume-basedir, -v TEXT`  <a name="ref-sam-cli-local-start-lambda-options-docker-volume-basedir"></a>
The location of the base directory where the Amazon SAM file exists. If Docker is running on a remote machine, you must mount the path where the Amazon SAM file exists on the Docker machine, and modify this value to match the remote machine.

`--env-vars, -n PATH`  <a name="ref-sam-cli-local-start-lambda-options-env-vars"></a>
The JSON or `.env` file that contains values for the Lambda function's environment variables. The file format is automatically detected.

`--force-image-build`  <a name="ref-sam-cli-local-start-lambda-options-force-image-build"></a>
Specify whether the CLI should rebuild the image used for invoking functions with layers.

`--help`  <a name="ref-sam-cli-local-start-lambda-options-help"></a>
Shows this message and exits.

`--hook-name TEXT`  <a name="ref-sam-cli-local-start-lambda-options-hook-name"></a>
The name of the hook that is used to extend Amazon SAM CLI functionality.  
Accepted values: `terraform`.

`--host TEXT`  <a name="ref-sam-cli-local-start-lambda-options-host"></a>
The local hostname or IP address to bind to (default: '127.0.0.1').

`--invoke-image TEXT`  <a name="ref-sam-cli-local-start-lambda-options-invoke-image"></a>
The URI of the container image that you want to use for the local function invocation.  
For Lambda functions with `PackageType: Zip`, this overrides the runtime base image. By default, Amazon SAM pulls the container image from Amazon ECR Public. Use this option to pull the image from another location.  
For Lambda functions with `PackageType: Image`, this overrides the `ImageUri` from the built template. Use this to invoke a different application image locally without modifying your template.  
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 functions in your application. For example, `sam local start-lambda --invoke-image public.ecr.aws/sam/emu-python3.13`. 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 example, `sam local start-lambda --invoke-image public.ecr.aws/sam/emu-python3.13 --invoke-image Function1=amazon/aws-sam-cli-emulation-image-python3.13`. With key-value pairs, you can specify different container images for different resources.

`--layer-cache-basedir DIRECTORY`  <a name="ref-sam-cli-local-start-lambda-options-layer-cache-basedir"></a>
Specifies the location basedir where the layers your template uses are downloaded to.

`--log-file, -l TEXT`  <a name="ref-sam-cli-local-start-lambda-options-log-file"></a>
The log file to send runtime logs to.

`--no-memory-limit`  <a name="ref-sam-cli-local-start-lambda-options-no-memory-limit"></a>
Removes the memory limitation in the container during local invoke, even when memory is configured in the Amazon SAM template.

`--parameter-overrides`  <a name="ref-sam-cli-local-start-lambda-options-parameter-overrides"></a>
A string that contains Amazon CloudFormation parameter overrides encoded as key-value pairs. Use the same format as the Amazon Command Line Interface (Amazon CLI). The Amazon SAM CLI format is explicit key and value keywords, each override is separated by a space. Here are two examples:  
+ `--parameter-overrides ParameterKey=hello,ParameterValue=world`
+ `--parameter-overrides ParameterKey=hello,ParameterValue=world ParameterKey=example1,ParameterValue=example2 ParameterKey=apple,ParameterValue=banana`

`--port, -p INTEGER`  <a name="ref-sam-cli-local-start-lambda-options-port"></a>
The local port number to listen on (default: '3001').

`--profile TEXT`  <a name="ref-sam-cli-local-start-lambda-options-profile"></a>
The specific profile from your credential file that gets Amazon credentials.

`--region TEXT`  <a name="ref-sam-cli-local-start-lambda-options-region"></a>
The Amazon Region to deploy to. For example, us-east-1.

`--save-params`  <a name="ref-sam-cli-local-start-lambda-options-save-params"></a>
Save the parameters that you provide at the command line to the Amazon SAM configuration file.

`--shutdown`  <a name="ref-sam-cli-local-start-lambda-options-shutdown"></a>
Emulates a shutdown event after the invoke completes, in order to test extension handling of shutdown behavior.

`--skip-prepare-infra`  <a name="ref-sam-cli-local-start-lambda-options-skip-prepare-infra"></a>
Skips the preparation stage if no infrastructure changes have been made. Use with the `--hook-name` option.

`--skip-pull-image`  <a name="ref-sam-cli-local-start-lambda-options-skip-pull-image"></a>
Specifies whether the CLI should skip pulling down the latest Docker image for the Lambda runtime.

`--template, -t PATH`  <a name="ref-sam-cli-local-start-lambda-options-template"></a>
The Amazon SAM template file.  
If you specify this option, Amazon SAM loads only the template and the local resources that it points to. This option is not compatible with `--hook-name`.

`--terraform-plan-file`  <a name="ref-sam-cli-local-start-lambda-options-terraform-plan-file"></a>
The relative or absolute path to your local Terraform plan file when using the Amazon SAM CLI with Terraform Cloud. This option requires that `--hook-name` be set to `terraform`.

`--warm-containers [EAGER | LAZY]`  <a name="ref-sam-cli-local-start-lambda-options-warm-containers"></a>
Optional. Specifies how Amazon SAM CLI manages containers for each function.  
Two options are available:  
+ `EAGER`: Containers for all functions are loaded at startup and persist between invocations.
+ `LAZY`: Containers are only loaded when each function is first invoked. Those containers persist for additional invocations.

## Example
<a name="sam-cli-command-reference-sam-local-start-lambda-examples"></a>

For a detailed example and in-depth walkthrough on using the `sam local start-lambda` subcommand, refer to [Introduction to testing with sam local start-lambda](using-sam-cli-local-start-lambda.md).