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 start

You can also use Profiles.

Core

Options that affect the core LocalStack system.

VariableExample ValuesDescription
DEBUG0 (default) |1Flag to increase log level and print more verbose logs (useful for troubleshooting issues)
IMAGE_NAMElocalstack/localstack (default), localstack/localstack:0.11.0Specific name and tag of LocalStack Docker image to use.
GATEWAY_LISTEN0.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_HOSTlocalhost.localstack.cloud:4566 (default)This is interpolated into URLs and addresses that are returned by LocalStack. It has the form <hostname>:<port>.
USE_SSL0 (default)Whether to return URLs using HTTP (0) or HTTPS (1).
LEGACY_DIRECTORIES0 (default)Use legacy method of managing internal filesystem layout. See Filesystem Layout.
PERSISTENCE0 (default)Enable persistence. See Persistence Mechanism and Filesystem Layout.
MAIN_CONTAINER_NAMElocalstack-main (default)Specify the main docker container name
LS_LOGtrace, trace-internal, debug, info, warn, error, warningSpecify the log level. Currently overrides the DEBUG configuration. trace for detailed request/response, trace-internal for internal calls, too.
EXTERNAL_SERVICE_PORTS_START4510 (default)Start of the External Service Port Range (inclusive).
EXTERNAL_SERVICE_PORTS_END4560 (default)End of the External Service Port Range (exclusive).
EAGER_SERVICE_LOADING0 (default) |1Boolean 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.
SERVICESs3,sqsA 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_REGIONS0 (default)Allows the use of non-standard AWS regions. By default, LocalStack only accepts standard AWS regions.
PARITY_AWS_ACCESS_KEY_ID0 (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.

VariableExample ValuesDescription
LOCALSTACK_VOLUME_DIR~/.cache/localstack/volume (on Linux)The location on the host of the LocalStack volume directory mount. See Filesystem Layout
CONFIG_PROFILEThe configuration profile to load. See Profiles
CONFIG_DIR~/.localstackThe path where LocalStack can find configuration profiles and other CLI-specific configuration

Docker

Options to configure how LocalStack interacts with Docker.

VariableExample ValuesDescription
DOCKER_FLAGSAllows to pass custom flags (e.g., volume mounts) to “docker run” when running LocalStack in Docker.
DOCKER_SOCK/var/run/docker.sockPath to local Docker UNIX domain socket
DOCKER_BRIDGE_IP172.17.0.1IP of the docker bridge used to enable access between containers
LEGACY_DOCKER_CLIENT0|1Whether LocalStack should use the command-line Docker client and subprocess execution to run Docker commands, rather than the Docker SDK.
DOCKER_CMDdocker (default), sudo dockerShell command used to run Docker containers (only used in combination with LEGACY_DOCKER_CLIENT)
FORCE_NONINTERACTIVEWhen 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

VariableExample ValuesDescription
GRAPHQL_ENDPOINT_STRATEGYlegacy|domain|pathGoverns how AppSync endpoints are created to access a GraphQL API (see AppSync Endpoints)

Batch

VariableExample ValuesDescription
BATCH_DOCKER_FLAGS-e TEST_ENV=1337Additional flags provided to the batch container. Same restrictions as LAMBDA_DOCKER_FLAGS.

BigData (EMR, Athena, Glue)

VariableExample ValuesDescription
BIGDATA_DOCKER_NETWORKNetwork 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_FLAGSAdditional flags for the bigdata container. Same restrictions as LAMBDA_DOCKER_FLAGS.

DynamoDB

VariableExample ValuesDescription
DYNAMODB_ERROR_PROBABILITYDecimal value between 0.0(default) and 1.0Randomly inject ProvisionedThroughputExceededException errors into DynamoDB API responses.
DYNAMODB_HEAP_SIZE256m (default), 1GSets the JAVA EE maximum memory size for DynamoDB; full table scans require more memory
DYNAMODB_SHARE_DB0|1When activated, DynamodDB will use a single database instead of separate databases for each credential and region.
DYNAMODB_IN_MEMORY0 (default) |1When 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_STARTUP0|1Optimize the database tables in the store before starting
DYNAMODB_DELAY_TRANSIENT_STATUSES0|1When 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

VariableExample ValuesDescription
ECS_REMOVE_CONTAINERS0|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.4Additional flags passed to Docker when creating ECS task containers. Same restrictions as LAMBDA_DOCKER_FLAGS.

EC2

VariableExample ValuesDescription
EC2_DOCKER_FLAGS--privilegedAdditional flags passed to Docker when launching containerized instances. Same restrictions as LAMBDA_DOCKER_FLAGS.
EC2_DOWNLOAD_DEFAULT_IMAGES0|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_DEVICES1|0 (default)Whether to create and mount user-specified EBS block devices into EC2 container instances.
EC2_EBS_MAX_VOLUME_SIZE1000 (default)Maximum size (in MBs) of user-specified EBS block devices mounted into EC2 container instances.

EKS

VariableExample ValuesDescription
EKS_LOADBALANCER_PORT8081 (default)Local port on which the Kubernetes load balancer is exposed on the host.
EKS_K3S_IMAGE_TAGv1.22.6-k3s1 (default)Custom tag of the k8s/rancher image used to spin up Kubernetes clusters locally.

ElastiCache

VariableExample ValuesDescription
PROVIDER_OVERRIDE_ELASTICACHElegacyUse the legacy ElastiCache provider.

Elasticsearch

IAM

VariableExample ValuesDescription
ENFORCE_IAM0 (default)|1Enable IAM policy evaluation and enforcement. If this is disabled (the default), IAM policies will have no effect to your requests.
IAM_SOFT_MODE0 (default)|1Enable 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

VariableExample ValuesDescription
KINESIS_ERROR_PROBABILITYDecimal value between 0.0(default) and 1.0Randomly inject ProvisionedThroughputExceededException errors into Kinesis API responses.
KINESIS_SHARD_LIMIT100 (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_LIMIT10 (default), Infinity (to disable)Integer value , causing the Kinesis API to start throwing exceptions to mimic the default on demand stream count limit.
KINESIS_LATENCY500 (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

VariableExample ValuesDescription
BUCKET_MARKER_LOCALhot-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:ipAdditional 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_NETWORKbridge (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_LAYERS1 (default, pro)Whether to download public Lambda layers from AWS through a LocalStack proxy when creating or updating functions.
LAMBDA_IGNORE_ARCHITECTURE0 (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_PREFIXamazon/aws-lambda- (default, pro)Prefix for images that will be used to execute Lambda functions in Kubernetes.
LAMBDA_KEEPALIVE_MS600000 (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_EXECUTIONS1000 (default)The maximum number of events that functions can process simultaneously in the current Region. See AWS service quotas
LAMBDA_LIMITS_CREATE_FUNCTION_REQUEST_SIZE69905067 (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_CONTAINERS1 (default)Whether to remove any Lambda Docker containers.
LAMBDA_RUNTIME_ENVIRONMENT_TIMEOUT10 (default)How many seconds Lambda will wait for the runtime environment to start up.
LAMBDA_RUNTIME_EXECUTORdocker (default)Where Lambdas will be executed.
kubernetes (pro)Execute lambdas in a Kubernetes cluster.
LAMBDA_RUNTIME_IMAGE_MAPPINGbase images for Lambda (default)Customize the Docker image of Lambda runtimes, either by:
a) pattern with <runtime> placeholder, e.g. custom-repo/lambda-<runtime>:2022
b) json dict mapping the <runtime> to an image, e.g. {"python3.9": "custom-repo/lambda-py:thon3.9"}
LAMBDA_SYNCHRONOUS_CREATE0 (default)Set to 1 to create lambda functions synchronously (not recommended).
LAMBDA_TRUNCATE_STDOUT2000 (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

VariableExample ValuesDescription
MWAA_PIP_TRUSTED_HOSTSpypi.org,files.pythonhosted.orgComma-separated list of hosts for which SSL verification is not performed when installing Python dependencies for MWAA environment.

OpenSearch

VariableExample ValuesDescription
OPENSEARCH_CUSTOM_BACKENDhttp://opensearch:9200URL 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_CLUSTER0|1When 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_STRATEGYpath|domain|portGoverns how domain endpoints are created to access a cluster (see Opensearch Endpoints).

RDS

VariableExample ValuesDescription
RDS_CLUSTER_ENDPOINT_HOST_ONLY1 (default) / 0Whether the cluster endpoint returns the host only (which is AWS parity). If set to 0 it will return <host>:<port>.
RDS_PG_CUSTOM_VERSIONS0 / 1 (default)Whether to install and use custom Postgres versions for RDS (or alternatively, use default version 11).
RDS_MYSQL_DOCKER1 (default) / 0Whether 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_IMAGEmysql:8.0Defines a specific MySQL image that should be used when spinning up the MySQL engine. Only available if RDS_MYSQL_DOCKER is enabled.
MSSQL_IMAGEmcr.microsoft.com/mssql/server:2022-latestDefines a specific image that should be used when spinning up a SQL server engine.

S3

VariableExample ValuesDescription
S3_DIRConfigure 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_VALIDATION0 / 1 (default)Used to toggle validation of S3 pre-signed URL request signature. Set to 0 to validate.
S3_SKIP_KMS_KEY_VALIDATION0 / 1 (default)Used to toggle validation of provided KMS key in S3 operations.
PROVIDER_OVERRIDE_S3v3Activate the new LocalStack-native S3 provider.

StepFunctions

VariableExample ValuesDescription
PROVIDER_OVERRIDE_STEPFUNCTIONSlegacy / v2 (default)The new LocalStack-native StepFunctions provider (v2) is active by default since LocalStack 3.0.

SQS

VariableExample ValuesDescription
SQS_DELAY_PURGE_RETRY0 (default)Used to toggle PurgeQueueInProgress errors when making more than one PurgeQueue call within 60 seconds.
SQS_DELAY_RECENTLY_DELETED0 (default)Used to toggle QueueDeletedRecently errors when re-creating a queue within 60 seconds of deleting it.
SQS_ENDPOINT_STRATEGYstandard (default) | domain | path | offConfigures the format of Queue URLs (see SQS Queue URLs)
SQS_DISABLE_CLOUDWATCH_METRICS0 (default)Disables the CloudWatch Metrics for SQS when set to 1
SQS_CLOUDWATCH_METRICS_REPORT_INTERVAL60 (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

VariableExample ValuesDescription
DISABLE_CORS_HEADERS0 (default)Whether to disable the returning of default CORS headers in API responses (disables access from https://app.localstack.cloud).
DISABLE_CORS_CHECKS0 (default)Whether to disable all CSRF (server-side) mitigations.
DISABLE_CUSTOM_CORS_S30 (default)Whether to disable CORS override by S3.
DISABLE_CUSTOM_CORS_APIGATEWAY0 (default)Whether to disable CORS override by apigateway.
EXTRA_CORS_ALLOWED_ORIGINSComma-separated list of origins that are allowed to communicate with localstack.
EXTRA_CORS_ALLOWED_HEADERSComma-separated list of header names to be be added to Access-Control-Allow-Headers CORS header.
EXTRA_CORS_EXPOSE_HEADERSComma-separated list of header names to be be added to Access-Control-Expose-Headers CORS header.
ENABLE_CONFIG_UPDATES0 (default)Whether to enable dynamic configuration updates at runtime.

Emails

Please check with your SMTP email service provider for the following settings.

VariableExample ValuesDescription
SMTP_HOSTlocalhost:1025Hostname (and optionally the port) of the SMTP server. The port defaults to 25.
SMTP_USERLogin username for the SMTP server if required.
SMTP_PASSLogin password for the SMTP server if required.
SMTP_EMAILsender@example.comOrigin email address. Required for Cognito only.

Persistence

To learn more about these configuration options, see Persistence.

VariableValid optionsDescription
SNAPSHOT_SAVE_STRATEGYON_SHUTDOWN|ON_REQUEST|SCHEDULED|MANUALStrategy that governs when LocalStack should make state snapshots
SNAPSHOT_LOAD_STRATEGYON_STARTUP|ON_REQUEST|MANUALStrategy that governs when LocalStack restores state snapshots
SNAPSHOT_FLUSH_INTERVAL15 (default)The interval (in seconds) between persistence snapshots. It only applies to a SCHEDULED save strategy (see Persistence Mechanism)

Miscellaneous

VariableExample ValuesDescription
SKIP_SSL_CERT_DOWNLOADWhether to skip downloading the SSL certificate for localhost.localstack.cloud
CUSTOM_SSL_CERT_PATH/var/lib/localstack/custom/server.test.pemDefines the absolute path to a custom SSL certificate for localhost.localstack.cloud
IGNORE_ES_DOWNLOAD_ERRORSWhether to ignore errors (e.g., network/SSL) when downloading Elasticsearch plugins
OVERRIDE_IN_DOCKEROverrides 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_EVENTS1Whether to disable publishing LocalStack events
OUTBOUND_HTTP_PROXYhttp://10.10.1.3HTTP Proxy used for downloads of runtime dependencies and connections outside LocalStack itself
OUTBOUND_HTTPS_PROXYhttps://10.10.1.3HTTPS Proxy used for downloads of runtime dependencies and connections outside LocalStack itself
REQUESTS_CA_BUNDLE/var/lib/localstack/lib/ca_bundle.pemCA Bundle to be used to verify HTTPS requests made by LocalStack

Debugging

VariableExample ValuesDescription
DEVELOPStarts a debugpy server before starting LocalStack services
DEVELOP_PORTPort number for debugpy server
WAIT_FOR_DEBUGGERForces LocalStack to wait for a debugger to start the services

DNS

To learn more about these configuration options, see DNS Server.

VariableExample ValuesDescription
DNS_ADDRESS0.0.0.0 (default)Address the LocalStack should bind the DNS server on (port 53 tcp/udp). Value 0 to disable.
DNS_SERVER8.8.8.8 (default)Fallback DNS server for non-modified queries.
DNS_RESOLVE_IP127.0.0.1IP 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_PATTERNSNames which should be resolved to the LocalStack IP, as python-compatible regex.

LocalStack Pro

VariableExample ValuesDescription
ACTIVATE_PRO1 (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_API_KEYAPI key to activate LocalStack Pro.
LOG_LICENSE_ISSUES1 (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.

VariableExample ValuesDescription
BIGDATA_MONO_CONTAINER0|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_DOWNLOADSDeprecated. Whether to skip downloading additional infrastructure components (e.g., specific Elasticsearch versions)
STEPFUNCTIONS_LAMBDA_ENDPOINTdefaultDeprecated. 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.

Legacy

These configurations have already been removed and won’t have any effect on newer versions of LocalStack. +Please consult the migration guide for more information.

VariableExample ValuesDescription
BUCKET_MARKER_LOCALhot-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:ipAdditional 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_NETWORKbridge (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_LAYERS1 (default, pro)Whether to download public Lambda layers from AWS through a LocalStack proxy when creating or updating functions.
LAMBDA_IGNORE_ARCHITECTURE0 (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_PREFIXamazon/aws-lambda- (default, pro)Prefix for images that will be used to execute Lambda functions in Kubernetes.
LAMBDA_KEEPALIVE_MS600000 (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_EXECUTIONS1000 (default)The maximum number of events that functions can process simultaneously in the current Region. See AWS service quotas
LAMBDA_LIMITS_CREATE_FUNCTION_REQUEST_SIZE69905067 (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_CONTAINERS1 (default)Whether to remove any Lambda Docker containers.
LAMBDA_RUNTIME_ENVIRONMENT_TIMEOUT10 (default)How many seconds Lambda will wait for the runtime environment to start up.
LAMBDA_RUNTIME_EXECUTORdocker (default)Where Lambdas will be executed.
kubernetes (pro)Execute lambdas in a Kubernetes cluster.
LAMBDA_RUNTIME_IMAGE_MAPPINGbase images for Lambda (default)Customize the Docker image of Lambda runtimes, either by:
a) pattern with <runtime> placeholder, e.g. custom-repo/lambda-<runtime>:2022
b) json dict mapping the <runtime> to an image, e.g. {"python3.9": "custom-repo/lambda-py:thon3.9"}
LAMBDA_SYNCHRONOUS_CREATE0 (default)Set to 1 to create lambda functions synchronously (not recommended).
LAMBDA_TRUNCATE_STDOUT2000 (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

VariableExample ValuesDescription
MWAA_PIP_TRUSTED_HOSTSpypi.org,files.pythonhosted.orgComma-separated list of hosts for which SSL verification is not performed when installing Python dependencies for MWAA environment.

OpenSearch

VariableExample ValuesDescription
OPENSEARCH_CUSTOM_BACKENDhttp://opensearch:9200URL 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_CLUSTER0|1When 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_STRATEGYpath|domain|portGoverns how domain endpoints are created to access a cluster (see Opensearch Endpoints).

RDS

VariableExample ValuesDescription
RDS_CLUSTER_ENDPOINT_HOST_ONLY1 (default) / 0Whether the cluster endpoint returns the host only (which is AWS parity). If set to 0 it will return <host>:<port>.
RDS_PG_CUSTOM_VERSIONS0 / 1 (default)Whether to install and use custom Postgres versions for RDS (or alternatively, use default version 11).
RDS_MYSQL_DOCKER1 (default) / 0Whether 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_IMAGEmysql:8.0Defines a specific MySQL image that should be used when spinning up the MySQL engine. Only available if RDS_MYSQL_DOCKER is enabled.
MSSQL_IMAGEmcr.microsoft.com/mssql/server:2022-latestDefines a specific image that should be used when spinning up a SQL server engine.

S3

VariableExample ValuesDescription
S3_SKIP_SIGNATURE_VALIDATION0 / 1 (default)Used to toggle validation of S3 pre-signed URL request signature. Set to 0 to validate.
S3_SKIP_KMS_KEY_VALIDATION0 / 1 (default)Used to toggle validation of provided KMS key in S3 operations.
PROVIDER_OVERRIDE_S3legacy_v2 / v3 (default)The new LocalStack-native S3 provider (v3) is active by default since LocalStack 3.0.

StepFunctions

VariableExample ValuesDescription
PROVIDER_OVERRIDE_STEPFUNCTIONSlegacy / v2 (default)The new LocalStack-native StepFunctions provider (v2) is active by default since LocalStack 3.0.

SQS

VariableExample ValuesDescription
SQS_DELAY_PURGE_RETRY0 (default)Used to toggle PurgeQueueInProgress errors when making more than one PurgeQueue call within 60 seconds.
SQS_DELAY_RECENTLY_DELETED0 (default)Used to toggle QueueDeletedRecently errors when re-creating a queue within 60 seconds of deleting it.
SQS_ENDPOINT_STRATEGYstandard (default) | domain | path | offConfigures the format of Queue URLs (see SQS Queue URLs)
SQS_DISABLE_CLOUDWATCH_METRICS0 (default)Disables the CloudWatch Metrics for SQS when set to 1
SQS_CLOUDWATCH_METRICS_REPORT_INTERVAL60 (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

VariableExample ValuesDescription
DISABLE_CORS_HEADERS0 (default)Whether to disable the returning of default CORS headers in API responses (disables access from https://app.localstack.cloud).
DISABLE_CORS_CHECKS0 (default)Whether to disable all CSRF (server-side) mitigations.
DISABLE_CUSTOM_CORS_S30 (default)Whether to disable CORS override by S3.
DISABLE_CUSTOM_CORS_APIGATEWAY0 (default)Whether to disable CORS override by apigateway.
EXTRA_CORS_ALLOWED_ORIGINSComma-separated list of origins that are allowed to communicate with localstack.
EXTRA_CORS_ALLOWED_HEADERSComma-separated list of header names to be be added to Access-Control-Allow-Headers CORS header.
EXTRA_CORS_EXPOSE_HEADERSComma-separated list of header names to be be added to Access-Control-Expose-Headers CORS header.
ENABLE_CONFIG_UPDATES0 (default)Whether to enable dynamic configuration updates at runtime.

Emails

Please check with your SMTP email service provider for the following settings.

VariableExample ValuesDescription
SMTP_HOSTlocalhost:1025Hostname (and optionally the port) of the SMTP server. The port defaults to 25.
SMTP_USERLogin username for the SMTP server if required.
SMTP_PASSLogin password for the SMTP server if required.
SMTP_EMAILsender@example.comOrigin email address. Required for Cognito only.

Persistence

To learn more about these configuration options, see Persistence.

VariableValid optionsDescription
SNAPSHOT_SAVE_STRATEGYON_SHUTDOWN|ON_REQUEST|SCHEDULED|MANUALStrategy that governs when LocalStack should make state snapshots
SNAPSHOT_LOAD_STRATEGYON_STARTUP|ON_REQUEST|MANUALStrategy that governs when LocalStack restores state snapshots
SNAPSHOT_FLUSH_INTERVAL15 (default)The interval (in seconds) between persistence snapshots. It only applies to a SCHEDULED save strategy (see Persistence Mechanism)

Miscellaneous

VariableExample ValuesDescription
SKIP_SSL_CERT_DOWNLOADWhether to skip downloading the SSL certificate for localhost.localstack.cloud
CUSTOM_SSL_CERT_PATH/var/lib/localstack/custom/server.test.pemDefines the absolute path to a custom SSL certificate for localhost.localstack.cloud
IGNORE_ES_DOWNLOAD_ERRORSWhether to ignore errors (e.g., network/SSL) when downloading Elasticsearch plugins
OVERRIDE_IN_DOCKEROverrides 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_EVENTS1Whether to disable publishing LocalStack events
OUTBOUND_HTTP_PROXYhttp://10.10.1.3HTTP Proxy used for downloads of runtime dependencies and connections outside LocalStack itself
OUTBOUND_HTTPS_PROXYhttps://10.10.1.3HTTPS Proxy used for downloads of runtime dependencies and connections outside LocalStack itself
REQUESTS_CA_BUNDLE/var/lib/localstack/lib/ca_bundle.pemCA Bundle to be used to verify HTTPS requests made by LocalStack

Debugging

VariableExample ValuesDescription
DEVELOPStarts a debugpy server before starting LocalStack services
DEVELOP_PORTPort number for debugpy server
WAIT_FOR_DEBUGGERForces LocalStack to wait for a debugger to start the services

DNS

To learn more about these configuration options, see DNS Server.

VariableExample ValuesDescription
DNS_ADDRESS0.0.0.0 (default)Address the LocalStack should bind the DNS server on (port 53 tcp/udp). Value 0 to disable.
DNS_SERVER8.8.8.8 (default)Fallback DNS server for non-modified queries.
DNS_RESOLVE_IP127.0.0.1IP 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_PATTERNSNames which should be resolved to the LocalStack IP, as python-compatible regex.

LocalStack Pro

VariableExample ValuesDescription
ACTIVATE_PRO1 (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_API_KEYAPI key to activate LocalStack Pro.
LOG_LICENSE_ISSUES1 (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.

VariableExample ValuesDescription
BIGDATA_MONO_CONTAINER0|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_DOWNLOADSDeprecated. Whether to skip downloading additional infrastructure components (e.g., specific Elasticsearch versions)
STEPFUNCTIONS_LAMBDA_ENDPOINTdefaultDeprecated. 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_DIRDeprecated. 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.

VariableRemoved inDescription
DATA_DIR2.0.0Legacy. Local directory for saving persistent data. Use PERSISTENCE instead.
HOST_TMP_FOLDER2.0.0Legacy. 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_PATH2.0.0Legacy. 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.
TMPDIR2.0.0Legacy. Temporary folder on the host running the CLI and inside the LocalStack container .
<SERVICE>_BACKEND3.0.0Legacy. Custom endpoint URL to use for a specific service, where <SERVICE> is the uppercase service name.
ACTIVATE_NEW_POD_CLIENT3.0.0Legacy. Whether to use the new Cloud Pods client leveraging LocalStack container’s APIs.
ES_CUSTOM_BACKEND3.0.0Legacy. 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_STRATEGY3.0.0Legacy. Use OPENSEARCH_ENDPOINT_STRATEGY instead. Governs how domain endpoints are created to access a cluster (see Elasticsearch Endpoints)
ES_MULTI_CLUSTER3.0.0Legacy. 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_UNIMPLEMENTED3.0.0Legacy. 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. 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
@@ -304,7 +304,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

Last modified November 9, 2023: Partition old configuration into deprecation/legacy (#906) (164b8518f)