Configuration
Overview of configuration options in LocalStack
15 minute read
LocalStack exposes various configuration options to control its behaviour.
These options can be passed to LocalStack as environment variables like so:
$ DEBUG=1 localstack startYou can also use Profiles.
Core
Options that affect the core LocalStack system.
| Variable | Example Values | Description |
|---|---|---|
DEBUG | 0 (default) |1 | Flag to increase log level and print more verbose logs (useful for troubleshooting issues) |
IMAGE_NAME | localstack/localstack (default), localstack/localstack:0.11.0 | Specific name and tag of LocalStack Docker image to use. |
GATEWAY_LISTEN | 0.0.0.0:4566 (default in Docker mode) 127.0.0.1:4566 (default in host mode) | Configures the bind addresses of LocalStack. It has the form <ip address>:<port>(,<ip address>:<port>)*. LocalStack Pro adds port 443. |
LOCALSTACK_HOST | localhost.localstack.cloud:4566 (default) | This is interpolated into URLs and addresses that are returned by LocalStack. It has the form <hostname>:<port>. |
USE_SSL | 0 (default) | Whether to return URLs using HTTP (0) or HTTPS (1). |
LEGACY_DIRECTORIES | 0 (default) | Use legacy method of managing internal filesystem layout. See Filesystem Layout. |
PERSISTENCE | 0 (default) | Enable persistence. See Persistence Mechanism and Filesystem Layout. |
MAIN_CONTAINER_NAME | localstack-main (default) | Specify the main docker container name |
LS_LOG | trace, trace-internal, debug, info, warn, error, warning | Specify the log level. Currently overrides the DEBUG configuration. trace for detailed request/response, trace-internal for internal calls, too. |
EXTERNAL_SERVICE_PORTS_START | 4510 (default) | Start of the External Service Port Range (inclusive). |
EXTERNAL_SERVICE_PORTS_END | 4560 (default) | End of the External Service Port Range (exclusive). |
EAGER_SERVICE_LOADING | 0 (default) |1 | Boolean that toggles lazy loading of services. If eager loading is enabled, services are started at LocalStack startup rather than their first use. Be aware that eager loading increases the LocalStack startup time. |
SERVICES | s3,sqs | A comma-delimited string of services. Check the internal health endpoint /_localstack/health for valid service names. If SERVICES is set LocalStack will only load the listed services. All other services will be disabled and cannot be used. |
ALLOW_NONSTANDARD_REGIONS | 0 (default) | Allows the use of non-standard AWS regions. By default, LocalStack only accepts standard AWS regions. |
PARITY_AWS_ACCESS_KEY_ID | 0 (default) | Enables the use production-like access key IDs. By default, LocalStack issues keys with LSIA... and LKIA... prefix, and will reject keys that start with ASIA... or AKIA.... |
CLI
These options are applicable when using the CLI to start LocalStack.
| Variable | Example Values | Description |
|---|---|---|
LOCALSTACK_VOLUME_DIR | ~/.cache/localstack/volume (on Linux) | The location on the host of the LocalStack volume directory mount. See Filesystem Layout |
CONFIG_PROFILE | The configuration profile to load. See Profiles | |
CONFIG_DIR | ~/.localstack | The path where LocalStack can find configuration profiles and other CLI-specific configuration |
Docker
Options to configure how LocalStack interacts with Docker.
| Variable | Example Values | Description |
|---|---|---|
DOCKER_FLAGS | Allows to pass custom flags (e.g., volume mounts) to “docker run” when running LocalStack in Docker. | |
DOCKER_SOCK | /var/run/docker.sock | Path to local Docker UNIX domain socket |
DOCKER_BRIDGE_IP | 172.17.0.1 | IP of the docker bridge used to enable access between containers |
LEGACY_DOCKER_CLIENT | 0|1 | Whether LocalStack should use the command-line Docker client and subprocess execution to run Docker commands, rather than the Docker SDK. |
DOCKER_CMD | docker (default), sudo docker | Shell command used to run Docker containers (only used in combination with LEGACY_DOCKER_CLIENT) |
FORCE_NONINTERACTIVE | When running with Docker, disables the --interactive and --tty flags. Useful when running headless. |
Local AWS Services
This section covers configuration options that are specific to certain AWS services.
AppSync
| Variable | Example Values | Description |
|---|---|---|
GRAPHQL_ENDPOINT_STRATEGY | legacy|domain|path | Governs how AppSync endpoints are created to access a GraphQL API (see AppSync Endpoints) |
Batch
| Variable | Example Values | Description |
|---|---|---|
BATCH_DOCKER_FLAGS | -e TEST_ENV=1337 | Additional flags provided to the batch container. Same restrictions as LAMBDA_DOCKER_FLAGS. |
BigData (EMR, Athena, Glue)
| Variable | Example Values | Description |
|---|---|---|
BIGDATA_DOCKER_NETWORK | Network the bigdata should be connected to. The LocalStack container has to be connected to that network as well. Per default, the bigdata container will be connected to a network LocalStack is also connected to. | |
BIGDATA_DOCKER_FLAGS | Additional flags for the bigdata container. Same restrictions as LAMBDA_DOCKER_FLAGS. |
DocumentDB
| Variable | Example Values | Description |
|---|---|---|
DOCDB_PROXY_CONTAINER | 0 (default) |1 | Whether the DocumentDB starts the MongoDB container proxied over LocalStack container. When enabled lambda functions can use the LOCALSTACK_HOSTNAME env to connect to the DocumentDB. By default the container starts without proxy as standalone container. |
DynamoDB
| Variable | Example Values | Description |
|---|---|---|
DYNAMODB_ERROR_PROBABILITY | Decimal value between 0.0(default) and 1.0 | Randomly inject ProvisionedThroughputExceededException errors into DynamoDB API responses. |
DYNAMODB_HEAP_SIZE | 256m (default), 1G | Sets the JAVA EE maximum memory size for DynamoDB; full table scans require more memory |
DYNAMODB_SHARE_DB | 0|1 | When activated, DynamodDB will use a single database instead of separate databases for each credential and region. |
DYNAMODB_IN_MEMORY | 0 (default) |1 | When activated, DynamodDB will start in in-memory mode, which can have a faster throughput. If you use this options, both persistence and cloud pods will not work for DynamoDB |
DYNAMODB_OPTIMIZE_DB_BEFORE_STARTUP | 0|1 | Optimize the database tables in the store before starting |
DYNAMODB_DELAY_TRANSIENT_STATUSES | 0|1 | When activated, DynamoDB will introduce artificial delays in resource creation to simulate the actual cloud service more closely. Currently works only for CREATING and DELETING online index statuses. |
DYNAMODB_CORS | * | Enable CORS support for specific allow-list list the domains separated by , use * for public access (default is *) |
ECS
| Variable | Example Values | Description |
|---|---|---|
ECS_REMOVE_CONTAINERS | 0|1 (default) | Remove Docker containers associated with ECS tasks after execution. Disabling this and dumping container logs might help with troubleshooting failing ECS tasks. |
ECS_DOCKER_FLAGS | --privileged, --dns 1.2.3.4 | Additional flags passed to Docker when creating ECS task containers. Same restrictions as LAMBDA_DOCKER_FLAGS. |
EC2
| Variable | Example Values | Description |
|---|---|---|
EC2_DOCKER_FLAGS | --privileged | Additional flags passed to Docker when launching containerized instances. Same restrictions as LAMBDA_DOCKER_FLAGS. |
EC2_DOWNLOAD_DEFAULT_IMAGES | 0|1 (default) | At startup, LocalStack Pro downloads latest Ubuntu images from Docker Hub for use as AMIs. This can be disabled for security reasons. |
EC2_MOUNT_BLOCK_DEVICES | 1|0 (default) | Whether to create and mount user-specified EBS block devices into EC2 container instances. |
EC2_EBS_MAX_VOLUME_SIZE | 1000 (default) | Maximum size (in MBs) of user-specified EBS block devices mounted into EC2 container instances. |
EKS
| Variable | Example Values | Description |
|---|---|---|
EKS_LOADBALANCER_PORT | 8081 (default) | Local port on which the Kubernetes load balancer is exposed on the host. |
EKS_K3S_IMAGE_TAG | v1.22.6-k3s1 (default) | Custom tag of the k8s/rancher image used to spin up Kubernetes clusters locally. |
ElastiCache
| Variable | Example Values | Description |
|---|---|---|
PROVIDER_OVERRIDE_ELASTICACHE | legacy | Use the legacy ElastiCache provider. |
Elasticsearch
Note
The OpenSearch configuration variables are used to manage both OpenSearch and ElasticSearch clusters. -See here.IAM
| Variable | Example Values | Description |
|---|---|---|
ENFORCE_IAM | 0 (default)|1 | Enable IAM policy evaluation and enforcement. If this is disabled (the default), IAM policies will have no effect to your requests. |
IAM_SOFT_MODE | 0 (default)|1 | Enable IAM soft mode. This leads to policy evaluation without actually denying access. Needs ENFORCE_IAM enabled as well. For more information, see Identity and Access Management. |
Kinesis
| Variable | Example Values | Description |
|---|---|---|
KINESIS_ERROR_PROBABILITY | Decimal value between 0.0(default) and 1.0 | Randomly inject ProvisionedThroughputExceededException errors into Kinesis API responses. |
KINESIS_SHARD_LIMIT | 100 (default), Infinity (to disable) | Integer value , causing the Kinesis API to start throwing exceptions to mimic the default shard limit. |
KINESIS_ON_DEMAND_STREAM_COUNT_LIMIT | 10 (default), Infinity (to disable) | Integer value , causing the Kinesis API to start throwing exceptions to mimic the default on demand stream count limit. |
KINESIS_LATENCY | 500 (default), 0 (to disable) | Integer value of milliseconds, causing the Kinesis API to delay returning a response in order to mimic latency from a live AWS call. |
KINESIS_INITIALIZE_STREAMS | "my-first-stream:1,my-other-stream:2:us-west-2,my-last-stream:1" | A comma-delimited string of stream names, its corresponding shard count and an optional region to initialize during startup. If the region is not provided, the default region is used. Only works with the kinesis-mock KINESIS_PROVIDER. |
Lambda
Note
The legacy Lambda implementation has been removed since LocalStackĀ 3.0 (Dockerlatest since 2023-11-09).
-Please consult the migration guide for more information.| Variable | Example Values | Description |
|---|---|---|
BUCKET_MARKER_LOCAL | hot-reload (default) | Magic S3 bucket name for Hot Reloading. The S3Key points to the source code on the local file system. |
LAMBDA_DOCKER_FLAGS | -e KEY=VALUE, -v host:container, -p host:container, --add-host domain:ip | Additional flags passed to Docker run|create commands. Supports environment variables, ports, volume mounts, extra hosts, networks, DNS servers, labels, ulimits, user, platform, and privileged mode. |
LAMBDA_DOCKER_NETWORK | bridge (Docker default) | Docker network driver for the Lambda and ECS containers. Needs to be set to the network the LocalStack container is connected to. Limitation: host mode currently not supported. |
LAMBDA_DOWNLOAD_AWS_LAYERS | 1 (default, pro) | Whether to download public Lambda layers from AWS through a LocalStack proxy when creating or updating functions. |
LAMBDA_IGNORE_ARCHITECTURE | 0 (default) | Whether to ignore the AWS architectures (x86_64 or arm64) configured for the lambda function. Set to 1 to run cross-platform compatible lambda functions natively (i.e., Docker selects architecture). |
LAMBDA_K8S_IMAGE_PREFIX | amazon/aws-lambda- (default, pro) | Prefix for images that will be used to execute Lambda functions in Kubernetes. |
LAMBDA_KEEPALIVE_MS | 600000 (default 10min) | Time in milliseconds until lambda shuts down the execution environment after the last invocation has been processed. Set to 0 to immediately shut down the execution environment after an invocation. |
LAMBDA_LIMITS_CONCURRENT_EXECUTIONS | 1000 (default) | The maximum number of events that functions can process simultaneously in the current Region. See AWS service quotas |
LAMBDA_LIMITS_CREATE_FUNCTION_REQUEST_SIZE | 69905067 (default) | The maximum HTTP request size in bytes for the CreateFunction operation. Raising this limit enables the creation of larger Lambda functions without the need to upload the code to an S3 deployment bucket. |
LAMBDA_REMOVE_CONTAINERS | 1 (default) | Whether to remove any Lambda Docker containers. |
LAMBDA_RUNTIME_ENVIRONMENT_TIMEOUT | 10 (default) | How many seconds Lambda will wait for the runtime environment to start up. |
LAMBDA_RUNTIME_EXECUTOR | docker (default) | Where Lambdas will be executed. |
kubernetes (pro) | Execute lambdas in a Kubernetes cluster. | |
LAMBDA_RUNTIME_IMAGE_MAPPING | base images for Lambda (default) | Customize the Docker image of Lambda runtimes, either by: a) pattern with <runtime> placeholder, e.g. custom-repo/lambda-<runtime>:2022b) json dict mapping the <runtime> to an image, e.g. {"python3.9": "custom-repo/lambda-py:thon3.9"} |
LAMBDA_SYNCHRONOUS_CREATE | 0 (default) | Set to 1 to create lambda functions synchronously (not recommended). |
LAMBDA_TRUNCATE_STDOUT | 2000 (default) | Allows increasing the default char limit for truncation of lambda log lines when printed in the console. This does not affect the logs processing in CloudWatch. |
MWAA
| Variable | Example Values | Description |
|---|---|---|
MWAA_PIP_TRUSTED_HOSTS | pypi.org,files.pythonhosted.org | Comma-separated list of hosts for which SSL verification is not performed when installing Python dependencies for MWAA environment. |
OpenSearch
| Variable | Example Values | Description |
|---|---|---|
OPENSEARCH_CUSTOM_BACKEND | http://opensearch:9200 | URL to a custom OpenSearch backend cluster. If this is set to a valid URL, then LocalStack will not create OpenSearch cluster instances, but instead forward all domains to the given backend (see Custom Opensearch Backends). |
OPENSEARCH_MULTI_CLUSTER | 0|1 | When activated, LocalStack will spawn one OpenSearch cluster per domain. Otherwise all domains will share a single cluster instance. This is ignored if OPENSEARCH_CUSTOM_BACKEND is set. |
OPENSEARCH_ENDPOINT_STRATEGY | path|domain|port | Governs how domain endpoints are created to access a cluster (see Opensearch Endpoints). |
RDS
| Variable | Example Values | Description |
|---|---|---|
RDS_CLUSTER_ENDPOINT_HOST_ONLY | 1 (default) / 0 | Whether the cluster endpoint returns the host only (which is AWS parity). If set to 0 it will return <host>:<port>. |
RDS_PG_CUSTOM_VERSIONS | 0 / 1 (default) | Whether to install and use custom Postgres versions for RDS (or alternatively, use default version 11). |
RDS_MYSQL_DOCKER | 1 (default) / 0 | Whether to disable MySQL engines (and use MariaDB instead). MySQL engine for cluster/instances will start in a new docker container. If you have troubles running MySQL in docker, you can disable the feature. |
MYSQL_IMAGE | mysql:8.0 | Defines a specific MySQL image that should be used when spinning up the MySQL engine. Only available if RDS_MYSQL_DOCKER is enabled. |
MSSQL_IMAGE | mcr.microsoft.com/mssql/server:2022-latest | Defines a specific image that should be used when spinning up a SQL server engine. |
S3
| Variable | Example Values | Description |
|---|---|---|
S3_SKIP_SIGNATURE_VALIDATION | 0 / 1 (default) | Used to toggle validation of S3 pre-signed URL request signature. Set to 0 to validate. |
S3_SKIP_KMS_KEY_VALIDATION | 0 / 1 (default) | Used to toggle validation of provided KMS key in S3 operations. |
PROVIDER_OVERRIDE_S3 | legacy_v2 / v3 (default) | The new LocalStack-native S3 provider (v3) is active by default since LocalStack 3.0. |
StepFunctions
| Variable | Example Values | Description |
|---|---|---|
PROVIDER_OVERRIDE_STEPFUNCTIONS | legacy / v2 (default) | The new LocalStack-native StepFunctions provider (v2) is active by default since LocalStack 3.0. |
SQS
| Variable | Example Values | Description |
|---|---|---|
SQS_DELAY_PURGE_RETRY | 0 (default) | Used to toggle PurgeQueueInProgress errors when making more than one PurgeQueue call within 60 seconds. |
SQS_DELAY_RECENTLY_DELETED | 0 (default) | Used to toggle QueueDeletedRecently errors when re-creating a queue within 60 seconds of deleting it. |
SQS_ENDPOINT_STRATEGY | standard (default) | domain | path | off | Configures the format of Queue URLs (see SQS Queue URLs) |
SQS_DISABLE_CLOUDWATCH_METRICS | 0 (default) | Disables the CloudWatch Metrics for SQS when set to 1 |
SQS_CLOUDWATCH_METRICS_REPORT_INTERVAL | 60 (default) | Configures the report interval (in seconds) for Approximate* metrics that are sent to CloudWatch periodically. Sending will be disabled if SQS_DISABLE_CLOUDWATCH_METRICS=1 |
Security
Warning
Please be aware that the following options may have severe security implications.| Variable | Example Values | Description |
|---|---|---|
DISABLE_CORS_HEADERS | 0 (default) | Whether to disable the returning of default CORS headers in API responses (disables access from https://app.localstack.cloud). |
DISABLE_CORS_CHECKS | 0 (default) | Whether to disable all CSRF (server-side) mitigations. |
DISABLE_CUSTOM_CORS_S3 | 0 (default) | Whether to disable CORS override by S3. |
DISABLE_CUSTOM_CORS_APIGATEWAY | 0 (default) | Whether to disable CORS override by apigateway. |
EXTRA_CORS_ALLOWED_ORIGINS | Comma-separated list of origins that are allowed to communicate with localstack. | |
EXTRA_CORS_ALLOWED_HEADERS | Comma-separated list of header names to be be added to Access-Control-Allow-Headers CORS header. | |
EXTRA_CORS_EXPOSE_HEADERS | Comma-separated list of header names to be be added to Access-Control-Expose-Headers CORS header. | |
ENABLE_CONFIG_UPDATES | 0 (default) | Whether to enable dynamic configuration updates at runtime. |
Emails
Please check with your SMTP email service provider for the following settings.
| Variable | Example Values | Description |
|---|---|---|
SMTP_HOST | localhost:1025 | Hostname (and optionally the port) of the SMTP server. The port defaults to 25. |
SMTP_USER | Login username for the SMTP server if required. | |
SMTP_PASS | Login password for the SMTP server if required. | |
SMTP_EMAIL | sender@example.com | Origin email address. Required for Cognito only. |
Persistence
To learn more about these configuration options, see Persistence.
| Variable | Valid options | Description |
|---|---|---|
SNAPSHOT_SAVE_STRATEGY | ON_SHUTDOWN|ON_REQUEST|SCHEDULED|MANUAL | Strategy that governs when LocalStack should make state snapshots |
SNAPSHOT_LOAD_STRATEGY | ON_STARTUP|ON_REQUEST|MANUAL | Strategy that governs when LocalStack restores state snapshots |
SNAPSHOT_FLUSH_INTERVAL | 15 (default) | The interval (in seconds) between persistence snapshots. It only applies to a SCHEDULED save strategy (see Persistence Mechanism) |
Miscellaneous
| Variable | Example Values | Description |
|---|---|---|
SKIP_SSL_CERT_DOWNLOAD | Whether to skip downloading the SSL certificate for localhost.localstack.cloud | |
CUSTOM_SSL_CERT_PATH | /var/lib/localstack/custom/server.test.pem | Defines the absolute path to a custom SSL certificate for localhost.localstack.cloud |
IGNORE_ES_DOWNLOAD_ERRORS | Whether to ignore errors (e.g., network/SSL) when downloading Elasticsearch plugins | |
OVERRIDE_IN_DOCKER | Overrides the check whether LocalStack is executed within a docker container. If set to true, LocalStack assumes it runs in a docker container. Should not be set unless necessary. | |
DISABLE_EVENTS | 1 | Whether to disable publishing LocalStack events |
OUTBOUND_HTTP_PROXY | http://10.10.1.3 | HTTP Proxy used for downloads of runtime dependencies and connections outside LocalStack itself |
OUTBOUND_HTTPS_PROXY | https://10.10.1.3 | HTTPS Proxy used for downloads of runtime dependencies and connections outside LocalStack itself |
REQUESTS_CA_BUNDLE | /var/lib/localstack/lib/ca_bundle.pem | CA Bundle to be used to verify HTTPS requests made by LocalStack |
Debugging
| Variable | Example Values | Description |
|---|---|---|
DEVELOP | Starts a debugpy server before starting LocalStack services | |
DEVELOP_PORT | Port number for debugpy server | |
WAIT_FOR_DEBUGGER | Forces LocalStack to wait for a debugger to start the services |
DNS
To learn more about these configuration options, see DNS Server.
| Variable | Example Values | Description |
|---|---|---|
DNS_ADDRESS | 0.0.0.0 (default) | Address the LocalStack should bind the DNS server on (port 53 tcp/udp). Value 0 to disable. |
DNS_SERVER | 8.8.8.8 (default) | Fallback DNS server for non-modified queries. |
DNS_RESOLVE_IP | 127.0.0.1 | IP address the DNS integration should return as A record for modified queries. This will override any automatic detection of the proper response IP. |
DNS_LOCAL_NAME_PATTERNS | Names which should be resolved to the LocalStack IP, as python-compatible regex. |
LocalStack Pro
| Variable | Example Values | Description |
|---|---|---|
ACTIVATE_PRO | 1 (default) | Whether pro should be activated or not. This is set to true by default if using the localstack/localstack-pro container image. If set to 1, LocalStack will fail to start if the license key activation did not work. If set to 0, an attempt is made to start LocalStack without pro features. |
LOCALSTACK_AUTH_TOKEN | AUTH_TOKEN to activate LocalStack Pro. | |
LOG_LICENSE_ISSUES | 1 (default) | Whether to log issues with the license activation to the console. |
Deprecated
These configurations are deprecated and will be removed in the upcoming major version.
| Variable | Example Values | Description |
|---|---|---|
BIGDATA_MONO_CONTAINER | 0|1 (default) | Deprecated. Whether to spin Big Data services inside the LocalStack main container. Glue jobs breaks when using BIGDATA_MONO_CONTAINER=0. |
SKIP_INFRA_DOWNLOADS | Deprecated. Whether to skip downloading additional infrastructure components (e.g., specific Elasticsearch versions) | |
STEPFUNCTIONS_LAMBDA_ENDPOINT | default | Deprecated. This is only supported for the legacy provider. URL to use as the Lambda service endpoint in Step Functions. By default this is the LocalStack Lambda endpoint. Use default to select the original AWS Lambda endpoint. |
S3_DIR | Deprecated. This is only supported for the legacy_v2 provider. Configure a global parent directory that contains all buckets as sub-directories (S3_DIR=/path/to/root) or an individual directory that will get mounted as special bucket names (S3_DIR=/path/to/root/bucket1:bucket1). Only available for Localstack Pro. |
Legacy
These configurations have already been removed and won’t have any effect on newer versions of LocalStack. -Please remove them from your configuration.
| Variable | Removed in | Description |
|---|---|---|
DATA_DIR | 2.0.0 | Legacy. Local directory for saving persistent data. Use PERSISTENCE instead. |
HOST_TMP_FOLDER | 2.0.0 | Legacy. Temporary folder on the host that gets mounted as $TMPDIR/localstack into the LocalStack container. Required only for Lambda volume mounts when using LAMBDA_REMOTE_DOCKER=false. |
INIT_SCRIPTS_PATH | 2.0.0 | Legacy. Before 1.0, this was used to configure the path to the initializing files with extensions .sh that were found in /docker-entrypoint-initaws.d. This has been replaced by the init-hook system. |
TMPDIR | 2.0.0 | Legacy. Temporary folder on the host running the CLI and inside the LocalStack container . |
<SERVICE>_BACKEND | 3.0.0 | Legacy. Custom endpoint URL to use for a specific service, where <SERVICE> is the uppercase service name. |
ACTIVATE_NEW_POD_CLIENT | 3.0.0 | Legacy. Whether to use the new Cloud Pods client leveraging LocalStack container’s APIs. |
ES_CUSTOM_BACKEND | 3.0.0 | Legacy. Use OPENSEARCH_CUSTOM_BACKEND instead. URL to a custom elasticsearch backend cluster. If this is set to a valid URL, then localstack will not create elasticsearch cluster instances, but instead forward all domains to the given backend (see Custom Elasticsearch Backends). |
ES_ENDPOINT_STRATEGY | 3.0.0 | Legacy. Use OPENSEARCH_ENDPOINT_STRATEGY instead. Governs how domain endpoints are created to access a cluster (see Elasticsearch Endpoints) |
ES_MULTI_CLUSTER | 3.0.0 | Legacy. Use OPENSEARCH_MULTI_CLUSTER instead. When activated, LocalStack will spawn one Elasticsearch cluster per domain. Otherwise all domains will share a single cluster instance. This is ignored if ES_CUSTOM_BACKEND is set. |
MOCK_UNIMPLEMENTED | 3.0.0 | Legacy. Whether to return mocked success responses (instead of 501 errors) for currently unimplemented API methods |
Profiles
LocalStack supports configuration profiles which are stored in the ~/.localstack config directory.
+ Create project issue
Table of Contents
Configuration
Overview of configuration options in LocalStack
20 minute read
LocalStack exposes various configuration options to control its behaviour.
These options can be passed to LocalStack as environment variables like so:
$ DEBUG=1 localstack startYou can also use Profiles.
Configurations marked as Deprecated will be removed in the next major version. You can find previously removed configuration variables under Legacy.
Core
Options that affect the core LocalStack system.
| Variable | Example Values | Description |
|---|---|---|
DEBUG | 0 (default) |1 | Flag to increase log level and print more verbose logs (useful for troubleshooting issues) |
IMAGE_NAME | localstack/localstack (default), localstack/localstack:0.11.0 | Specific name and tag of LocalStack Docker image to use. |
GATEWAY_LISTEN | 0.0.0.0:4566 (default in Docker mode) 127.0.0.1:4566 (default in host mode) | Configures the bind addresses of LocalStack. It has the form <ip address>:<port>(,<ip address>:<port>)*. LocalStack Pro adds port 443. |
LOCALSTACK_HOST | localhost.localstack.cloud:4566 (default) | This is interpolated into URLs and addresses that are returned by LocalStack. It has the form <hostname>:<port>. |
USE_SSL | 0 (default) | Whether to return URLs using HTTP (0) or HTTPS (1). Changed with 3.0.0. In earlier versions this was toggling SSL support on or off. |
PERSISTENCE | 0 (default) | Enable persistence. See Persistence Mechanism and Filesystem Layout. |
MAIN_CONTAINER_NAME | localstack-main (default) | Specify the main docker container name |
LS_LOG | trace, trace-internal, debug, info, warn, error, warning | Specify the log level. Currently overrides the DEBUG configuration. trace for detailed request/response, trace-internal for internal calls, too. |
EXTERNAL_SERVICE_PORTS_START | 4510 (default) | Start of the External Service Port Range (inclusive). |
EXTERNAL_SERVICE_PORTS_END | 4560 (default) | End of the External Service Port Range (exclusive). |
EAGER_SERVICE_LOADING | 0 (default) |1 | Boolean that toggles lazy loading of services. If eager loading is enabled, services are started at LocalStack startup rather than their first use. Be aware that eager loading increases the LocalStack startup time. |
SERVICES | s3,sqs | A comma-delimited string of services. Check the internal health endpoint /_localstack/health for valid service names. If SERVICES is set LocalStack will only load the listed services. All other services will be disabled and cannot be used. |
ALLOW_NONSTANDARD_REGIONS | 0 (default) | Allows the use of non-standard AWS regions. By default, LocalStack only accepts standard AWS regions. |
PARITY_AWS_ACCESS_KEY_ID | 0 (default) | Enables the use production-like access key IDs. By default, LocalStack issues keys with LSIA... and LKIA... prefix, and will reject keys that start with ASIA... or AKIA.... |
CLI
These options are applicable when using the CLI to start LocalStack.
| Variable | Example Values | Description |
|---|---|---|
LOCALSTACK_VOLUME_DIR | ~/.cache/localstack/volume (on Linux) | The location on the host of the LocalStack volume directory mount. See Filesystem Layout |
CONFIG_PROFILE | The configuration profile to load. See Profiles | |
CONFIG_DIR | ~/.localstack | The path where LocalStack can find configuration profiles and other CLI-specific configuration |
Docker
Options to configure how LocalStack interacts with Docker.
| Variable | Example Values | Description |
|---|---|---|
DOCKER_FLAGS | Allows to pass custom flags (e.g., volume mounts) to “docker run” when running LocalStack in Docker. | |
DOCKER_SOCK | /var/run/docker.sock | Path to local Docker UNIX domain socket |
DOCKER_BRIDGE_IP | 172.17.0.1 | IP of the docker bridge used to enable access between containers |
LEGACY_DOCKER_CLIENT | 0|1 | Whether LocalStack should use the command-line Docker client and subprocess execution to run Docker commands, rather than the Docker SDK. |
DOCKER_CMD | docker (default), sudo docker | Shell command used to run Docker containers (only used in combination with LEGACY_DOCKER_CLIENT) |
FORCE_NONINTERACTIVE | When running with Docker, disables the --interactive and --tty flags. Useful when running headless. |
Local AWS Services
This section covers configuration options that are specific to certain AWS services.
AppSync
| Variable | Example Values | Description |
|---|---|---|
GRAPHQL_ENDPOINT_STRATEGY | legacy|domain|path | Governs how AppSync endpoints are created to access a GraphQL API (see AppSync Endpoints) |
Batch
| Variable | Example Values | Description |
|---|---|---|
BATCH_DOCKER_FLAGS | -e TEST_ENV=1337 | Additional flags provided to the batch container. Same restrictions as LAMBDA_DOCKER_FLAGS. |
BigData (EMR, Athena, Glue)
| Variable | Example Values | Description |
|---|---|---|
BIGDATA_DOCKER_NETWORK | Network the bigdata should be connected to. The LocalStack container has to be connected to that network as well. Per default, the bigdata container will be connected to a network LocalStack is also connected to. | |
BIGDATA_DOCKER_FLAGS | Additional flags for the bigdata container. Same restrictions as LAMBDA_DOCKER_FLAGS. |
DocumentDB
| Variable | Example Values | Description |
|---|---|---|
DOCDB_PROXY_CONTAINER | 0 (default) |1 | Whether the DocumentDB starts the MongoDB container proxied over LocalStack container. When enabled lambda functions can use the LOCALSTACK_HOSTNAME env to connect to the DocumentDB. By default the container starts without proxy as standalone container. |
DynamoDB
| Variable | Example Values | Description |
|---|---|---|
DYNAMODB_ERROR_PROBABILITY | Decimal value between 0.0(default) and 1.0 | Randomly inject ProvisionedThroughputExceededException errors into DynamoDB API responses. |
DYNAMODB_HEAP_SIZE | 256m (default), 1G | Sets the JAVA EE maximum memory size for DynamoDB; full table scans require more memory |
DYNAMODB_SHARE_DB | 0|1 | When activated, DynamodDB will use a single database instead of separate databases for each credential and region. |
DYNAMODB_IN_MEMORY | 0 (default) |1 | When activated, DynamodDB will start in in-memory mode, which can have a faster throughput. If you use this options, both persistence and cloud pods will not work for DynamoDB |
DYNAMODB_OPTIMIZE_DB_BEFORE_STARTUP | 0|1 | Optimize the database tables in the store before starting |
DYNAMODB_DELAY_TRANSIENT_STATUSES | 0|1 | When activated, DynamoDB will introduce artificial delays in resource creation to simulate the actual cloud service more closely. Currently works only for CREATING and DELETING online index statuses. |
DYNAMODB_CORS | * | Enable CORS support for specific allow-list list the domains separated by , use * for public access (default is *) |
ECS
| Variable | Example Values | Description |
|---|---|---|
ECS_REMOVE_CONTAINERS | 0|1 (default) | Remove Docker containers associated with ECS tasks after execution. Disabling this and dumping container logs might help with troubleshooting failing ECS tasks. |
ECS_DOCKER_FLAGS | --privileged, --dns 1.2.3.4 | Additional flags passed to Docker when creating ECS task containers. Same restrictions as LAMBDA_DOCKER_FLAGS. |
EC2
| Variable | Example Values | Description |
|---|---|---|
EC2_DOCKER_FLAGS | --privileged | Additional flags passed to Docker when launching containerized instances. Same restrictions as LAMBDA_DOCKER_FLAGS. |
EC2_DOWNLOAD_DEFAULT_IMAGES | 0|1 (default) | At startup, LocalStack Pro downloads latest Ubuntu images from Docker Hub for use as AMIs. This can be disabled for security reasons. |
EC2_MOUNT_BLOCK_DEVICES | 1|0 (default) | Whether to create and mount user-specified EBS block devices into EC2 container instances. |
EC2_EBS_MAX_VOLUME_SIZE | 1000 (default) | Maximum size (in MBs) of user-specified EBS block devices mounted into EC2 container instances. |
EKS
| Variable | Example Values | Description |
|---|---|---|
EKS_LOADBALANCER_PORT | 8081 (default) | Local port on which the Kubernetes load balancer is exposed on the host. |
EKS_K3S_IMAGE_TAG | v1.22.6-k3s1 (default) | Custom tag of the k8s/rancher image used to spin up Kubernetes clusters locally. |
ElastiCache
| Variable | Example Values | Description |
|---|---|---|
PROVIDER_OVERRIDE_ELASTICACHE | legacy | Use the legacy ElastiCache provider. |
Elasticsearch
Note
The OpenSearch configuration variables are used to manage both OpenSearch and ElasticSearch clusters. +See here.IAM
| Variable | Example Values | Description |
|---|---|---|
ENFORCE_IAM | 0 (default)|1 | Enable IAM policy evaluation and enforcement. If this is disabled (the default), IAM policies will have no effect to your requests. |
IAM_SOFT_MODE | 0 (default)|1 | Enable IAM soft mode. This leads to policy evaluation without actually denying access. Needs ENFORCE_IAM enabled as well. For more information, see Identity and Access Management. |
Kinesis
| Variable | Example Values | Description |
|---|---|---|
KINESIS_ERROR_PROBABILITY | Decimal value between 0.0(default) and 1.0 | Randomly inject ProvisionedThroughputExceededException errors into Kinesis API responses. |
KINESIS_SHARD_LIMIT | 100 (default), Infinity (to disable) | Integer value , causing the Kinesis API to start throwing exceptions to mimic the default shard limit. |
KINESIS_ON_DEMAND_STREAM_COUNT_LIMIT | 10 (default), Infinity (to disable) | Integer value , causing the Kinesis API to start throwing exceptions to mimic the default on demand stream count limit. |
KINESIS_LATENCY | 500 (default), 0 (to disable) | Integer value of milliseconds, causing the Kinesis API to delay returning a response in order to mimic latency from a live AWS call. |
Lambda
Note
The legacy Lambda implementation has been removed since LocalStackĀ 3.0 (Dockerlatest since 2023-11-09).
+Please consult the migration guide for more information.| Variable | Example Values | Description |
|---|---|---|
BUCKET_MARKER_LOCAL | hot-reload (default) | Magic S3 bucket name for Hot Reloading. The S3Key points to the source code on the local file system. |
HOSTNAME_FROM_LAMBDA | localstack | Endpoint host under which APIs are accessible from Lambda containers (optional). This can be useful in docker-compose stacks to use the local container hostname if neither IP address nor container name of the main container are available (e.g., in CI). Often used in combination with LAMBDA_DOCKER_NETWORK. |
LAMBDA_DOCKER_FLAGS | -e KEY=VALUE, -v host:container, -p host:container, --add-host domain:ip | Additional flags passed to Docker run|create commands. Supports environment variables, ports, volume mounts, extra hosts, networks, DNS servers, labels, ulimits, user, platform, and privileged mode. |
LAMBDA_DOCKER_NETWORK | bridge (Docker default) | Docker network driver for the Lambda and ECS containers. Needs to be set to the network the LocalStack container is connected to. Limitation: host mode currently not supported. |
LAMBDA_DOWNLOAD_AWS_LAYERS | 1 (default, pro) | Whether to download public Lambda layers from AWS through a LocalStack proxy when creating or updating functions. |
LAMBDA_IGNORE_ARCHITECTURE | 0 (default) | Whether to ignore the AWS architectures (x86_64 or arm64) configured for the lambda function. Set to 1 to run cross-platform compatible lambda functions natively (i.e., Docker selects architecture). |
LAMBDA_K8S_IMAGE_PREFIX | amazon/aws-lambda- (default, pro) | Prefix for images that will be used to execute Lambda functions in Kubernetes. |
LAMBDA_KEEPALIVE_MS | 600000 (default 10min) | Time in milliseconds until lambda shuts down the execution environment after the last invocation has been processed. Set to 0 to immediately shut down the execution environment after an invocation. |
LAMBDA_LIMITS_CONCURRENT_EXECUTIONS | 1000 (default) | The maximum number of events that functions can process simultaneously in the current Region. See AWS service quotas |
LAMBDA_LIMITS_CREATE_FUNCTION_REQUEST_SIZE | 69905067 (default) | The maximum HTTP request size in bytes for the CreateFunction operation. Raising this limit enables the creation of larger Lambda functions without the need to upload the code to an S3 deployment bucket. |
LAMBDA_REMOVE_CONTAINERS | 1 (default) | Whether to remove any Lambda Docker containers. |
LAMBDA_RUNTIME_ENVIRONMENT_TIMEOUT | 10 (default) | How many seconds Lambda will wait for the runtime environment to start up. |
LAMBDA_RUNTIME_EXECUTOR | docker (default) | Where Lambdas will be executed. |
kubernetes (pro) | Execute lambdas in a Kubernetes cluster. | |
LAMBDA_RUNTIME_IMAGE_MAPPING | base images for Lambda (default) | Customize the Docker image of Lambda runtimes, either by: a) pattern with <runtime> placeholder, e.g. custom-repo/lambda-<runtime>:2022b) json dict mapping the <runtime> to an image, e.g. {"python3.9": "custom-repo/lambda-py:thon3.9"} |
LAMBDA_SYNCHRONOUS_CREATE | 0 (default) | Set to 1 to create lambda functions synchronously (not recommended). |
LAMBDA_TRUNCATE_STDOUT | 2000 (default) | Allows increasing the default char limit for truncation of lambda log lines when printed in the console. This does not affect the logs processing in CloudWatch. |
MWAA
| Variable | Example Values | Description |
|---|---|---|
MWAA_PIP_TRUSTED_HOSTS | pypi.org,files.pythonhosted.org | Comma-separated list of hosts for which SSL verification is not performed when installing Python dependencies for MWAA environment. |
OpenSearch
| Variable | Example Values | Description |
|---|---|---|
OPENSEARCH_CUSTOM_BACKEND | http://opensearch:9200 | URL to a custom OpenSearch backend cluster. If this is set to a valid URL, then LocalStack will not create OpenSearch cluster instances, but instead forward all domains to the given backend (see Custom Opensearch Backends). |
OPENSEARCH_MULTI_CLUSTER | 1| 0 | When activated, LocalStack will spawn one OpenSearch cluster per domain. Otherwise all domains will share a single cluster instance. This is ignored if OPENSEARCH_CUSTOM_BACKEND is set. |
OPENSEARCH_ENDPOINT_STRATEGY | path|domain|port | Governs how domain endpoints are created to access a cluster (see Opensearch Endpoints). |
SKIP_INFRA_DOWNLOADS | 1 | 0 (default) | Deprecated since 1.3.0 Whether to skip downloading additional infrastructure components (e.g., specific Elasticsearch versions) |
RDS
| Variable | Example Values | Description |
|---|---|---|
RDS_CLUSTER_ENDPOINT_HOST_ONLY | 1 (default) | 0 | Whether the cluster endpoint returns the host only (which is AWS parity). If set to 0 it will return <host>:<port>. |
RDS_PG_CUSTOM_VERSIONS | 0 | 1 (default) | Whether to install and use custom Postgres versions for RDS (or alternatively, use default version 11). |
RDS_MYSQL_DOCKER | 1 (default) | 0 | Whether to disable MySQL engines (and use MariaDB instead). MySQL engine for cluster/instances will start in a new docker container. If you have troubles running MySQL in docker, you can disable the feature. |
MYSQL_IMAGE | mysql:8.0 | Defines a specific MySQL image that should be used when spinning up the MySQL engine. Only available if RDS_MYSQL_DOCKER is enabled. |
MSSQL_IMAGE | mcr.microsoft.com/mssql/server:2022-latest | Defines a specific image that should be used when spinning up a SQL server engine. |
S3
| Variable | Example Values | Description |
|---|---|---|
S3_DIR | Deprecated since 3.0.0 This is only supported for the legacy_v2 provider. Configure a global parent directory that contains all buckets as sub-directories (S3_DIR=/path/to/root) or an individual directory that will get mounted as special bucket names (S3_DIR=/path/to/root/bucket1:bucket1). Only available for Localstack Pro. | |
S3_SKIP_SIGNATURE_VALIDATION | 0 | 1 (default) | Used to toggle validation of S3 pre-signed URL request signature. Set to 0 to validate. |
S3_SKIP_KMS_KEY_VALIDATION | 0 | 1 (default) | Used to toggle validation of provided KMS key in S3 operations. |
PROVIDER_OVERRIDE_S3 | legacy_v2 | v3 (default) | The new LocalStack-native S3 provider (v3) is active by default since LocalStack 3.0. |
StepFunctions
| Variable | Example Values | Description |
|---|---|---|
PROVIDER_OVERRIDE_STEPFUNCTIONS | legacy | v2 (default) | The new LocalStack-native StepFunctions provider (v2) is active by default since LocalStack 3.0. |
STEPFUNCTIONS_LAMBDA_ENDPOINT | default | Deprecated since 3.0.0 This is only supported for the legacy provider. URL to use as the Lambda service endpoint in Step Functions. By default this is the LocalStack Lambda endpoint. Use default to select the original AWS Lambda endpoint.Removed in new provider. |
SQS
| Variable | Example Values | Description |
|---|---|---|
SQS_DELAY_PURGE_RETRY | 0 (default) | Used to toggle PurgeQueueInProgress errors when making more than one PurgeQueue call within 60 seconds. |
SQS_DELAY_RECENTLY_DELETED | 0 (default) | Used to toggle QueueDeletedRecently errors when re-creating a queue within 60 seconds of deleting it. |
SQS_ENDPOINT_STRATEGY | standard (default) | domain | path | off | Configures the format of Queue URLs (see SQS Queue URLs) |
SQS_DISABLE_CLOUDWATCH_METRICS | 0 (default) | Disables the CloudWatch Metrics for SQS when set to 1 |
SQS_CLOUDWATCH_METRICS_REPORT_INTERVAL | 60 (default) | Configures the report interval (in seconds) for Approximate* metrics that are sent to CloudWatch periodically. Sending will be disabled if SQS_DISABLE_CLOUDWATCH_METRICS=1 |
Security
Warning
Please be aware that the following options may have severe security implications.| Variable | Example Values | Description |
|---|---|---|
DISABLE_CORS_HEADERS | 0 (default) | Whether to disable the returning of default CORS headers in API responses (disables access from https://app.localstack.cloud). |
DISABLE_CORS_CHECKS | 0 (default) | Whether to disable all CSRF (server-side) mitigations. |
DISABLE_CUSTOM_CORS_S3 | 0 (default) | Whether to disable CORS override by S3. |
DISABLE_CUSTOM_CORS_APIGATEWAY | 0 (default) | Whether to disable CORS override by apigateway. |
EXTRA_CORS_ALLOWED_ORIGINS | Comma-separated list of origins that are allowed to communicate with localstack. | |
EXTRA_CORS_ALLOWED_HEADERS | Comma-separated list of header names to be be added to Access-Control-Allow-Headers CORS header. | |
EXTRA_CORS_EXPOSE_HEADERS | Comma-separated list of header names to be be added to Access-Control-Expose-Headers CORS header. | |
ENABLE_CONFIG_UPDATES | 0 (default) | Whether to enable dynamic configuration updates at runtime. |
Emails
Please check with your SMTP email service provider for the following settings.
| Variable | Example Values | Description |
|---|---|---|
SMTP_HOST | localhost:1025 | Hostname (and optionally the port) of the SMTP server. The port defaults to 25. |
SMTP_USER | Login username for the SMTP server if required. | |
SMTP_PASS | Login password for the SMTP server if required. | |
SMTP_EMAIL | sender@example.com | Origin email address. Required for Cognito only. |
Persistence
To learn more about these configuration options, see Persistence.
| Variable | Valid options | Description |
|---|---|---|
SNAPSHOT_SAVE_STRATEGY | ON_SHUTDOWN|ON_REQUEST|SCHEDULED|MANUAL | Strategy that governs when LocalStack should make state snapshots |
SNAPSHOT_LOAD_STRATEGY | ON_STARTUP|ON_REQUEST|MANUAL | Strategy that governs when LocalStack restores state snapshots |
SNAPSHOT_FLUSH_INTERVAL | 15 (default) | The interval (in seconds) between persistence snapshots. It only applies to a SCHEDULED save strategy (see Persistence Mechanism) |
Miscellaneous
| Variable | Example Values | Description |
|---|---|---|
SKIP_SSL_CERT_DOWNLOAD | Whether to skip downloading the SSL certificate for localhost.localstack.cloud | |
CUSTOM_SSL_CERT_PATH | /var/lib/localstack/custom/server.test.pem | Defines the absolute path to a custom SSL certificate for localhost.localstack.cloud |
IGNORE_ES_DOWNLOAD_ERRORS | Whether to ignore errors (e.g., network/SSL) when downloading Elasticsearch plugins | |
OVERRIDE_IN_DOCKER | Overrides the check whether LocalStack is executed within a docker container. If set to true, LocalStack assumes it runs in a docker container. Should not be set unless necessary. | |
DISABLE_EVENTS | 1 | Whether to disable publishing LocalStack events |
OUTBOUND_HTTP_PROXY | http://10.10.1.3 | HTTP Proxy used for downloads of runtime dependencies and connections outside LocalStack itself |
OUTBOUND_HTTPS_PROXY | https://10.10.1.3 | HTTPS Proxy used for downloads of runtime dependencies and connections outside LocalStack itself |
REQUESTS_CA_BUNDLE | /var/lib/localstack/lib/ca_bundle.pem | CA Bundle to be used to verify HTTPS requests made by LocalStack |
Debugging
| Variable | Example Values | Description |
|---|---|---|
DEVELOP | Starts a debugpy server before starting LocalStack services | |
DEVELOP_PORT | Port number for debugpy server | |
WAIT_FOR_DEBUGGER | Forces LocalStack to wait for a debugger to start the services |
DNS
To learn more about these configuration options, see DNS Server.
| Variable | Example Values | Description |
|---|---|---|
DNS_ADDRESS | 0.0.0.0 (default) | Address the LocalStack should bind the DNS server on (port 53 tcp/udp). Value 0 to disable. |
DNS_SERVER | 8.8.8.8 (default) | Fallback DNS server for non-modified queries. |
DNS_RESOLVE_IP | 127.0.0.1 | IP address the DNS integration should return as A record for modified queries. This will override any automatic detection of the proper response IP. |
DNS_LOCAL_NAME_PATTERNS | Names which should be resolved to the LocalStack IP, as python-compatible regex. |
LocalStack Pro
| Variable | Example Values | Description |
|---|---|---|
ACTIVATE_PRO | 1 (default) | Whether pro should be activated or not. This is set to true by default if using the localstack/localstack-pro container image. If set to 1, LocalStack will fail to start if the license key activation did not work. If set to 0, an attempt is made to start LocalStack without pro features. |
LOCALSTACK_AUTH_TOKEN | AUTH_TOKEN to activate LocalStack Pro. | |
LOG_LICENSE_ISSUES | 1 (default) | Whether to log issues with the license activation to the console. |
Legacy
These configurations have already been removed and won’t have any effect on newer versions of LocalStack. +Please remove them from your configuration.
| Variable | Removed in | Example Values | Description |
|---|---|---|---|
<SERVICE>_BACKEND | 3.0.0 | http://localhost:7577 | Custom endpoint URL to use for a specific service, where <SERVICE> is the uppercase service name. |
<SERVICE>_PORT_EXTERNAL | 3.0.0 | 4567 | Port number to expose a specific service externally . SQS_PORT_EXTERNAL, e.g. , is used when returning queue URLs from the SQS service to the client. |
ACTIVATE_NEW_POD_CLIENT | 3.0.0 | 0|1 (default) | Whether to use the new Cloud Pods client leveraging LocalStack container’s APIs. |
BIGDATA_MONO_CONTAINER | 3.0.0 | 0|1 (default) | Whether to spin Big Data services inside the LocalStack main container. Glue jobs breaks when using BIGDATA_MONO_CONTAINER=0. |
DEFAULT_REGION | 3.0.0 | us-east-1 (default) | AWS region to use when talking to the API (needs to be activated via USE_SINGLE_REGION=1). LocalStack now has full multi-region support. |
EDGE_BIND_HOST | 3.0.0 | 127.0.0.1 (default), 0.0.0.0 (docker) | Address the edge service binds to. Use GATEWAY_LISTEN instead. |
EDGE_FORWARD_URL | 3.0.0 | http://10.0.10.5678 | Optional target URL to forward all edge requests to (e.g., for distributed deployments) |
EDGE_PORT | 3.0.0 | 4566 (default) | Port number for the edge service, the main entry point for all API invocations. |
EDGE_PORT_HTTP | 3.0.0 | 4566 (default) | Port number for the edge service, the main entry point for all API invocations. |
ES_CUSTOM_BACKEND | 3.0.0 | http://elasticsearch:9200 | Use OPENSEARCH_CUSTOM_BACKEND instead. URL to a custom elasticsearch backend cluster. If this is set to a valid URL, then localstack will not create elasticsearch cluster instances, but instead forward all domains to the given backend (see Custom Elasticsearch Backends). |
ES_ENDPOINT_STRATEGY | 3.0.0 | path|domain|port (formerly off) | Use OPENSEARCH_ENDPOINT_STRATEGY instead. Governs how domain endpoints are created to access a cluster (see Elasticsearch Endpoints) |
ES_MULTI_CLUSTER | 3.0.0 | 0|1 | Use OPENSEARCH_MULTI_CLUSTER instead. When activated, LocalStack will spawn one Elasticsearch cluster per domain. Otherwise all domains will share a single cluster instance. This is ignored if ES_CUSTOM_BACKEND is set. |
HOSTNAME_EXTERNAL | 3.0.0 | localhost (default) | Name of the host to expose the services externally. This host is used, e.g., when returning queue URLs from the SQS service to the client. Use LOCALSTACK_HOST instead. |
KINESIS_INITIALIZE_STREAMS | 3.0.0 | "my-first-stream:1,my-other-stream:2:us-west-2,my-last-stream:1" | A comma-delimited string of stream names, its corresponding shard count and an optional region to initialize during startup. If the region is not provided, the default region is used. Only works with the kinesis-mock KINESIS_PROVIDER. |
KINESIS_PROVIDER | 3.0.0 | kinesis-mock (default) and kinesalite | |
KMS_PROVIDER | 3.0.0 | moto (default), local-kms | local-kms has been removed. |
LAMBDA_CODE_EXTRACT_TIME | 3.0.0 | 25 (default) | Time in seconds to wait at max while extracting Lambda code. By default, it is 25 seconds for limiting the execution time to avoid client/network timeout issues. Removed in new provider because function creation happens asynchronously. |
LAMBDA_CONTAINER_REGISTRY | 3.0.0 | lambci/lambda (default) | An alternative docker registry from where to pull lambda execution containers. Replaced by LAMBDA_RUNTIME_IMAGE_MAPPING in new provider. |
LAMBDA_EXECUTOR | 3.0.0 | Method to use for executing Lambda functions. For docker and docker-reuse, if LocalStack itself is started inside Docker, then the docker command needs to be available inside the container (usually requires to run the container in privileged mode). More information in Lambda Executor Modes.Removed in new provider. Mount the Docker socket or see migration guide. | |
docker (default) | Run each function invocation in a separate Docker container. | ||
local (fallback) | Run Lambda functions in a temporary directory on the local machine. | ||
docker-reuse | Create one Docker container per function and reuse it across invocations. | ||
LAMBDA_FALLBACK_URL | 3.0.0 | Fallback URL to use when a non-existing Lambda is invoked. Either records invocations in DynamoDB (value dynamodb://<table_name>) or forwards invocations as a POST request (value http(s)://...).Removed in new provider. | |
LAMBDA_FORWARD_URL | 3.0.0 | URL used to forward all Lambda invocations (useful to run Lambdas via an external service). Removed in new provider. | |
LAMBDA_JAVA_OPTS | 3.0.0 | -Xmx512M | Allow passing custom JVM options to Java Lambdas executed in Docker. Use _debug_port_ placeholder to configure the debug port, e.g., -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=_debug_port_.Currently not supported in new provider but possible via custom entrypoint. |
LAMBDA_REMOTE_DOCKER | 3.0.0 | determines whether Lambda code is copied or mounted into containers. Removed in new provider because zip file copying is used by default and hot reloading automatically configures mounting. | |
true (default) | your Lambda function definitions will be passed to the container by copying the zip file (potentially slower). It allows for remote execution, where the host and the client are not on the same machine. | ||
false | your Lambda function definitions will be passed to the container by mounting a volume (potentially faster). This requires to have the Docker client and the Docker host on the same machine. | ||
LAMBDA_STAY_OPEN_MODE | 3.0.0 | 1 (default) | Usage of the stay-open mode of Lambda containers. Only applicable if LAMBDA_EXECUTOR=docker-reuse. Set to 0 if you want to use Hot Reloading.Removed in new provider because stay-open mode is the default behavior. LAMBDA_KEEPALIVE_MS can be used to configure how long containers should be kept running in-between invocations. |
LAMBDA_XRAY_INIT | 3.0.0 | 1 | 0 (default) | Whether to fully initialize XRay daemon for Lambda containers (may increase Lambda startup times). the X-Ray daemon is now always initialized. |
LEGACY_EDGE_PROXY | 3.0.0 | 1 | 0 (default) | Whether to use the legacy edge proxy or the newer Gateway/HandlerChain framework. |
LOCALSTACK_HOSTNAME | 3.0.0 | http://${LOCALSTACK_HOSTNAME}:4566 | Name of the host where LocalStack services are available. Use this hostname as endpoint in order to access the services from within your Lambda functions (e.g., to store an item to DynamoDB or S3 from a Lambda). This option is read-only. Use LOCALSTACK_HOST instead. |
MOCK_UNIMPLEMENTED | 3.0.0 | 1 | 0 (default) | Whether to return mocked success responses (instead of 501 errors) for currently unimplemented API methods |
PERSIST_ALL | 3.0.0 | true (default) | Whether to persist all resources (including user code like Lambda functions), or only “light-weight” resources (e.g., SQS queues, or Cognito users). Can be set to false to reduce storage size of DATA_DIR folders or Cloud Pods. |
SYNCHRONOUS_KINESIS_EVENTS | 3.0.0 | 1 (default) | 0 | Whether or not to handle Kinesis Lambda event sources as synchronous invocations. |
USE_SINGLE_REGION | 3.0.0 | 1 | 0 (default) | Whether to use the legacy single-region mode, defined via DEFAULT_REGION. |
DATA_DIR | 2.0.0 | blank (disabled/default), /tmp/localstack/data | Local directory for saving persistent data. Use PERSISTENCE instead. |
DISABLE_TERM_HANDLER | 2.0.0 | "" (default) | 1 | Whether to disable signal passing to LocalStack when running in docker. Enabling this will prevent an orderly shutdown when running inside LS in docker. Setting this to anything else than an empty string will disable it. |
HOST_TMP_FOLDER | 2.0.0 | /some/path | Temporary folder on the host that gets mounted as $TMPDIR/localstack into the LocalStack container. Required only for Lambda volume mounts when using LAMBDA_REMOTE_DOCKER=false. |
INIT_SCRIPTS_PATH | 2.0.0 | /some/path | Before 1.0, this was used to configure the path to the initializing files with extensions .sh that were found in /docker-entrypoint-initaws.d. This has been replaced by the init-hook system. |
LEGACY_DIRECTORIES | 2.0.0 | 0 (default) | Use legacy method of managing internal filesystem layout. See Filesystem Layout. |
LEGACY_INIT_DIR | 2.0.0 | 1 | 0(default) | Used with INIT_SCRIPTS_PATH. This has been replaced by the init-hook system. |
MULTI_ACCOUNTS | 2.0.0 | 0 (default) | Enable multi-accounts (preview) |
REQUIRE_PRO | 2.0.0 | 0 (default) | Whether to require license activation to succeed to start LocalStack. If set to 0 (default) LocalStack will start as community version if the license cannot be activated. |
SQS_PROVIDER | 2.0.0 | moto (default) and elasticmq | |
SYNCHRONOUS_API_GATEWAY_EVENTS | 2.0.0 | 1 (default) | 0 | Whether or not to handle API Gateway Lambda event sources as synchronous invocations. |
SYNCHRONOUS_DYNAMODB_EVENTS | 2.0.0 | 1 (default) | 0 | Whether or not to handle DynamoDB Lambda event sources as synchronous invocations. |
SYNCHRONOUS_SQS_EVENTS | 2.0.0 | 1 | 0 (default) | Whether or not to handle SQS Lambda event sources as synchronous invocations. |
SYNCHRONOUS_SNS_EVENTS | 2.0.0 | 1 | 0 (default) | Whether or not to handle SNS Lambda event sources as synchronous invocations. |
TMPDIR | 2.0.0 | /tmp (default) | Temporary folder on the host running the CLI and inside the LocalStack container . |
USE_LIGHT_IMAGE | 2.0.0 | 1 (default) | Whether to use the light-weight Docker image. Overwritten by IMAGE_NAME. |
LEGACY_PERSISTENCE | 1.0.0 | true (default) | Whether to enable legacy persistence mechanism based on API calls record & replay. Only relevant for Community version, not relevant for advanced persistence mechanism in Pro. |
PERSISTENCE_SINGLE_FILE | 1.0.0 | true (default) | Specify if persistence files should be combined (only relevant for legacy persistence in Community version, not relevant for advanced persistence in Pro version). |
PORT_WEB_UI | 0.12.8 | 8080 (default) | Port for the legacy Web UI. Replaced by our Web Application |
Profiles
LocalStack supports configuration profiles which are stored in the ~/.localstack config directory.
A configuration profile is a set of environment variables stored in an .env file in the LocalStack config directory.
Here is an example of what configuration profiles might look like:
$ tree ~/.localstack
/home/username/.localstack
āāā default.env
@@ -322,7 +322,7 @@
Let’s take an example to load the dev.env profile file if it exists:$ python -m localstack.cli.main --profile=dev start
If no profile is specified, the default.env profile will be loaded.
While explicitly specified, the environment variables will always overwrite the profile.
To display the config environment variables, you can use the following command:
$ python -m localstack.cli.main --profile=dev config show
Note
The CONFIG_PROFILE is a CLI feature and cannot be used with a Docker/Docker Compose setup.
You can look at alternative means of setting environment variables for your Docker Compose setups.
-For Docker setups, we recommend passing the environment variables directly to the docker run command.
Last modified November 16, 2023: update docs with new license management flow and UX (#864) (e72c11cdf)docker run command.Last modified November 20, 2023: Collect more legacy configurations (#918) (38cc8633d)
Replace test-layer and 1 with the name and version number of your layer, respectively.
After granting access, the next time you reference the layer in one of your local Lambda functions using the AWS Lambda layer ARN, the layer will be automatically pulled down and integrated into your local dev environment.
Resource Browser
The LocalStack Web Application provides a Resource Browser for managing Lambda resources. You can access the Resource Browser by opening the LocalStack Web Application in your browser, navigating to the Resources section, and then clicking on Lambda under the Compute section.
The Resource Browser displays Functions and Layers resources. You can click on individual resources to view their details.
The Resource Browser allows you to perform the following actions:
- Create Functions & Layers: Create a new Lambda function or a new Lambda Layer by clicking on Create API button on top-right and creating a new configuration by clicking on Submit button.
- View Function & Layer Details: Click on any function or layer to view detailed information such as the resource’s name, ARN, runtime, handler, and more. You can also navigate across different versions of the resource.
- Delete Functions & Layers: To delete a function or layer, select the resource from the Resource Browser, click on the Remove Selected button at the top-right of the screen, and confirm the deletion by clicking on the Continue button.
Migrating to Lambda v2
Note
The legacy Lambda implementation has been removed since LocalStackĀ 3.0 (Dockerlatest since 2023-11-09).As part of the LocalStack 2.0 release, the Lambda provider has been migrated to v2 (formerly known as asf).
-With the new implementation, the following changes have been introduced:
- To run Lambda functions in LocalStack, mount the Docker socket into the LocalStack container. Add the following Docker volume mount to your LocalStack startup configuration:
/var/run/docker.sock:/var/run/docker.sock. You can find an example of this configuration in our officialdocker-compose.ymlfile. - The
v2provider discontinues Lambda Executor Modes such asLAMBDA_EXECUTOR=local. Previously, this mode was used as a fallback when the Docker socket was unavailable in the LocalStack container, but many users unintentionally used it instead of the configuredLAMBDA_EXECUTOR=docker. The new provider now behaves similarly to the olddocker-reuseexecutor and does not require such configuration. - The Lambda containers are now reused between invocations. The changes made to the filesystem (such as in
/tmp) will persist between subsequent invocations if the function is dispatched to the same container. This is known as a warm start (see Operating Lambda for more information). To ensure that each invocation starts with a fresh container, you can set theLAMBDA_KEEPALIVE_MSconfiguration option to 0 milliseconds, to force cold starts. - The platform uses official Docker base images pulled from
public.ecr.aws/lambda/, instead oflambci, and supports botharm64andx86_64architectures. The Lambda functions filesystem now matches the AWS Lambda production environment. The ARM containers for compatible runtimes are based on Amazon Linux 2, and ARM-compatible hosts can create functions with thearm64architecture. - Lambda functions in LocalStack resolve AWS domains, such as
s3.amazonaws.com, to the LocalStack container. This domain resolution is DNS-based and can be disabled by settingDNS_ADDRESS=0. For more information, refer to Transparent Endpoint Injection. Previously, LocalStack provided patched AWS SDKs to redirect AWS API calls transparently to LocalStack. - The new provider may generate more exceptions due to invalid input. For instance, while the old provider accepted arbitrary strings (such as
r1) as Lambda roles when creating a function, the new provider validates role ARNs using a regular expression that requires them to be in the formatarn:aws:iam::000000000000:role/lambda-role. However, it currently does not verify whether the role actually exists. - The new Lambda provider now follows the AWS Lambda state model, while creating and updating Lambda functions, which allows for asynchronous processing. Functions are always created in the
Pending stateand move toActiveonce they are ready to accept invocations. Previously, the functions were created synchronously by blocking until the function state was active. The configurationLAMBDA_SYNCHRONOUS_CREATE=1can force synchronous function creation, but it is not recommended. - LocalStack’s Lambda implementation, allows you to customize the Lambda execution environment using the Lambda Extensions API. This API allows for advanced monitoring, observability, or developer tooling, providing greater control and flexibility over your Lambda functions. Lambda functions can also be run on hosts with multi-architecture support, allowing you to leverage LocalStack’s Lambda API to develop and test Lambda functions with high parity.
The following configuration options from the old provider are discontinued in the new provider:
- The
LAMBDA_EXECUTORand specifically, theLAMBDA_EXECUTOR=localoptions are no longer supported. - The
LAMBDA_STAY_OPEN_MODEis now the default behavior and can be removed. Instead, use theLAMBDA_KEEPALIVE_MSoption to configure how long containers should be kept running in between invocations. - The
LAMBDA_REMOTE_DOCKERoption is not used anymore since the new provider automatically copies zip files and configures hot reloading. - The
LAMBDA_CODE_EXTRACT_TIMEoption is no longer used because function creation is now asynchronous. - The
HOSTNAME_FROM_LAMBDA,LAMBDA_FALLBACK_URL,SYNCHRONOUS_KINESIS_EVENTS,SYNCHRONOUS_SNS_EVENTSandLAMBDA_FORWARD_URLoptions are currently not supported. - The
LAMBDA_CONTAINER_REGISTRYoption is not used anymore. Instead, use the more flexibleLAMBDA_RUNTIME_IMAGE_MAPPINGoption to customize individual runtimes. - The
LAMBDA_XRAY_INIToption is no longer needed because the X-Ray daemon is always initialized.
However, the new provider still supports the following configuration options:
- The
BUCKET_MARKER_LOCALoption has a new default value,hot-reload. The former default value__local__is an invalid bucket name. - The
LAMBDA_TRUNCATE_STDOUToption. - The
LAMBDA_DOCKER_NETWORKoption. - The
LAMBDA_DOCKER_FLAGSoption. - The
LAMBDA_REMOVE_CONTAINERSoption. - The
LAMBDA_DOCKER_DNSoption since LocalStack 2.2.
Examples
The following code snippets and sample applications provide practical examples of how to use Lambda in LocalStack for various use cases:
- Lambda Hot Reloading shows how to use hot reloading to update function code and layers without having to redeploy them.
- Lambda Code Mounting and Debugging demonstrates how to debug Lambda functions locally using code mounting.
- Lambda Function URL shows how to use HTTP to invoke a Lambda function via its Function URL.
- Lambda Layers demonstrates how to use Lambda layers, which are reusable packages of code that can be shared across multiple functions.
- Lambda PHP/Bref shows how to use PHP/Bref with and without fpm, using the Serverless framework and AWS CDK.
- Lambda Container Images demonstrates how to use Lambda functions packaged as container images, which can be built using Docker and pushed to a local ECR registry.
- Lambda X-Ray shows how to instrument Lambda functions for X-Ray using Powertools and the X-Ray SDK.
Troubleshooting
Docker not available
In the old Lambda provider, Lambda functions were executed within the LocalStack container using the local executor mode. This mode was used as a fallback if the Docker socket was unavailable in the LocalStack container. However, many users inadvertently used the local executor mode instead of the intended Docker executor mode, which caused unexpected behavior.
If you encounter the following error message, you may be using the local executor mode:
Lambda 'arn:aws:lambda:us-east-1:000000000000:function:my-function:$LATEST' changed to failed. Reason: Docker not available
+With the new implementation, the following changes have been introduced:- To run Lambda functions in LocalStack, mount the Docker socket into the LocalStack container. Add the following Docker volume mount to your LocalStack startup configuration:
/var/run/docker.sock:/var/run/docker.sock. You can find an example of this configuration in our official docker-compose.yml file. - The
v2 provider discontinues Lambda Executor Modes such as LAMBDA_EXECUTOR=local. Previously, this mode was used as a fallback when the Docker socket was unavailable in the LocalStack container, but many users unintentionally used it instead of the configured LAMBDA_EXECUTOR=docker. The new provider now behaves similarly to the old docker-reuse executor and does not require such configuration. - The Lambda containers are now reused between invocations. The changes made to the filesystem (such as in
/tmp) will persist between subsequent invocations if the function is dispatched to the same container. This is known as a warm start (see Operating Lambda for more information). To ensure that each invocation starts with a fresh container, you can set the LAMBDA_KEEPALIVE_MS configuration option to 0 milliseconds, to force cold starts. - The platform uses official Docker base images pulled from
public.ecr.aws/lambda/, instead of lambci, and supports both arm64 and x86_64 architectures. The Lambda functions filesystem now matches the AWS Lambda production environment. The ARM containers for compatible runtimes are based on Amazon Linux 2, and ARM-compatible hosts can create functions with the arm64 architecture. - Lambda functions in LocalStack resolve AWS domains, such as
s3.amazonaws.com, to the LocalStack container. This domain resolution is DNS-based and can be disabled by setting DNS_ADDRESS=0. For more information, refer to Transparent Endpoint Injection. Previously, LocalStack provided patched AWS SDKs to redirect AWS API calls transparently to LocalStack. - The new provider may generate more exceptions due to invalid input. For instance, while the old provider accepted arbitrary strings (such as
r1) as Lambda roles when creating a function, the new provider validates role ARNs using a regular expression that requires them to be in the format arn:aws:iam::000000000000:role/lambda-role. However, it currently does not verify whether the role actually exists. - The new Lambda provider now follows the AWS Lambda state model, while creating and updating Lambda functions, which allows for asynchronous processing. Functions are always created in the
Pending state and move to Active once they are ready to accept invocations. Previously, the functions were created synchronously by blocking until the function state was active. The configuration LAMBDA_SYNCHRONOUS_CREATE=1 can force synchronous function creation, but it is not recommended. - LocalStack’s Lambda implementation, allows you to customize the Lambda execution environment using the Lambda Extensions API. This API allows for advanced monitoring, observability, or developer tooling, providing greater control and flexibility over your Lambda functions. Lambda functions can also be run on hosts with multi-architecture support, allowing you to leverage LocalStack’s Lambda API to develop and test Lambda functions with high parity.
The following configuration options from the old provider are discontinued in the new provider:
- The
LAMBDA_EXECUTOR and specifically, the LAMBDA_EXECUTOR=local options are no longer supported. - The
LAMBDA_STAY_OPEN_MODE is now the default behavior and can be removed. Instead, use the LAMBDA_KEEPALIVE_MS option to configure how long containers should be kept running in between invocations. - The
LAMBDA_REMOTE_DOCKER option is not used anymore since the new provider automatically copies zip files and configures hot reloading. - The
LAMBDA_CODE_EXTRACT_TIME option is no longer used because function creation is now asynchronous. - The
LAMBDA_FALLBACK_URL, SYNCHRONOUS_KINESIS_EVENTS, SYNCHRONOUS_SNS_EVENTS and LAMBDA_FORWARD_URL options are currently not supported. - The
LAMBDA_CONTAINER_REGISTRY option is not used anymore. Instead, use the more flexible LAMBDA_RUNTIME_IMAGE_MAPPING option to customize individual runtimes. - The
LAMBDA_XRAY_INIT option is no longer needed because the X-Ray daemon is always initialized.
However, the new provider still supports the following configuration options:
- The
BUCKET_MARKER_LOCAL option has a new default value, hot-reload. The former default value __local__ is an invalid bucket name. - The
LAMBDA_TRUNCATE_STDOUT option. - The
LAMBDA_DOCKER_NETWORK option. - The
LAMBDA_DOCKER_FLAGS option. - The
LAMBDA_REMOVE_CONTAINERS option. - The
LAMBDA_DOCKER_DNS option since LocalStack 2.2. - The
HOSTNAME_FROM_LAMBDA option since LocalStack 3.0.
Examples
The following code snippets and sample applications provide practical examples of how to use Lambda in LocalStack for various use cases:
- Lambda Hot Reloading shows how to use hot reloading to update function code and layers without having to redeploy them.
- Lambda Code Mounting and Debugging demonstrates how to debug Lambda functions locally using code mounting.
- Lambda Function URL shows how to use HTTP to invoke a Lambda function via its Function URL.
- Lambda Layers demonstrates how to use Lambda layers, which are reusable packages of code that can be shared across multiple functions.
- Lambda PHP/Bref shows how to use PHP/Bref with and without fpm, using the Serverless framework and AWS CDK.
- Lambda Container Images demonstrates how to use Lambda functions packaged as container images, which can be built using Docker and pushed to a local ECR registry.
- Lambda X-Ray shows how to instrument Lambda functions for X-Ray using Powertools and the X-Ray SDK.
Troubleshooting
Docker not available
In the old Lambda provider, Lambda functions were executed within the LocalStack container using the local executor mode. This mode was used as a fallback if the Docker socket was unavailable in the LocalStack container. However, many users inadvertently used the local executor mode instead of the intended Docker executor mode, which caused unexpected behavior.
If you encounter the following error message, you may be using the local executor mode:
Lambda 'arn:aws:lambda:us-east-1:000000000000:function:my-function:$LATEST' changed to failed. Reason: Docker not available
...
raise DockerNotAvailable("Docker not available")
An error occurred (ResourceConflictException) when calling the Invoke operation (reached max retries: 0): The operation cannot be performed at this time. The function is currently in the following state: Failed
Error: Failed to create/update the stack: sam-app, Waiter StackCreateComplete failed: Waiter encountered a terminal failure state: For expression "Stacks[].StackStatus" we matched expected path: "CREATE_FAILED" at least once
To fix this issue, add the Docker volume mount /var/run/docker.sock:/var/run/docker.sock to your LocalStack startup. Refer to our sample docker-compose.yml file as an example.
Function in Pending state
If you receive a ResourceConflictException when trying to invoke a function, it is currently in a Pending state and cannot be executed yet. To wait until the function becomes active, you can use the following command:
$ awslocal lambda get-function --function-name my-function
An error occurred (ResourceConflictException) when calling the Invoke operation (reached max retries: 0):
@@ -388,7 +388,7 @@
"LastUpdateStatus": "Successful",
...
}
-}
If the function is still in the Pending state, the output will include a "State": "Pending" field and a "StateReason": "The function is being created." message. Once the function is active, the "State" field will change to "Active" and the "LastUpdateStatus" field will indicate the status of the last update.
Not implemented error
If you are using LocalStack versions prior to 2.0, and encounter a NotImplementedError in the LocalStack logs and an InternalFailure (501) error in the client while creating a Lambda function using the CreateFunction API, check your PROVIDER_OVERRIDE_LAMBDA configuration. You might encounter this error if it is set to legacy.
Last modified November 9, 2023: Remove lambda legacy options (#899) (27afd5f43)If the function is still in the Pending state, the output will include a "State": "Pending" field and a "StateReason": "The function is being created." message. Once the function is active, the "State" field will change to "Active" and the "LastUpdateStatus" field will indicate the status of the last update.
Not implemented error
If you are using LocalStack versions prior to 2.0, and encounter a NotImplementedError in the LocalStack logs and an InternalFailure (501) error in the client while creating a Lambda function using the CreateFunction API, check your PROVIDER_OVERRIDE_LAMBDA configuration. You might encounter this error if it is set to legacy.
Last modified November 20, 2023: Collect more legacy configurations (#918) (38cc8633d)