Configuration

    LocalStack allows for many different configuration options. You can pass these via environment variables, e.g., like the following:

    These variables are only relevant 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
    CONFIG_DIR~/.localstackThe path where LocalStack can find configuration profiles and other CLI-specific configuration

    Docker

    Docker is used extensively by LocalStack, and there are several configuration parameters for 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 values 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. Only flags for volumes, ports, environment variables and add-hosts are allowed.

    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.
    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_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_CORSEnable CORS support for specific allow-list list the domains separated by use for public access (default is *)

    EKS

    VariableExample ValuesDescription
    EKS_LOADBALANCER_PORT8081 (default)Local port on which the Kubernetes load balancer is exposed on the host.

    Elasticsearch

    Deprecated

    While the ElasticSearch API is actively maintained, the configuration variables for ElasticSearch have been deprecated. Please use the OpenSearch configuration variables instead. The OpenSearch configuration variables are used to manage both, OpenSearch and ElasticSearch clusters.

    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.
    LEGACY_IAM_PROVIDER0 (default)|1(deprecated) Enable the pre-1.0 legacy IAM provider
    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_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.
    VariableExample ValuesDescription
    LAMBDAEXECUTORMethod 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.
    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-reuseCreate one Docker container per function and reuse it across invocations.
    LAMBDA_STAY_OPEN_MODE1 (default)Usage of the of Lambda containers. Only applicable if LAMBDA_EXECUTOR=docker-reuse. Set to 0 if you want to use Hot Swapping.
    LAMBDA_REMOTE_DOCKERdetermines whether Lambda code is copied or mounted into containers
    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.
    falseyour 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_TRUNCATE_STDOUT2000Allows increasing the default char value for truncation of lambda logs.
    BUCKET_MARKER_LOCALOptional bucket name for running lambdas locally.
    LAMBDA_CODE_EXTRACT_TIME25Time 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.
    LAMBDA_DOCKER_NETWORKOptional Docker network for the container running your lambda function. This configuration value also applies to ECS containers. Needs to be set to the network the LocalStack container is connected to if not default bridge network.
    LAMBDA_DOCKER_DNSOptional DNS server for the container running your lambda function.
    LAMBDA_DOCKER_FLAGS-e KEY=VALUE, -v host:container, -p host:container, —add-host domain:ipAdditional flags passed to Lambda Docker run|create commands (e.g., useful for specifying custom volume mounts). Does only support environment, volume, port and add-host flags
    LAMBDA_CONTAINER_REGISTRYlambci/lambda (default)An alternative docker registry from where to pull lambda execution containers.
    LAMBDA_REMOVE_CONTAINERS1 (default)Whether to remove containers after Lambdas being inactive for 10 minutes. Only applicable when using docker-reuse executor.
    LAMBDA_FALLBACK_URLFallback 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)://…).
    LAMBDA_FORWARD_URLURL used to forward all Lambda invocations (useful to run Lambdas via an external service).
    LAMBDA_JAVA_OPTS-Xmx512MAllow passing custom JVM options to Java Lambdas executed in Docker. Use _debug_port placeholder to configure the debug port, e.g., -agentlib:jdwp=transport=dtsocket,server=y,suspend=y,address=_debug_port.
    HOSTNAME_FROM_LAMBDAlocalstackEndpoint 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_XRAY_INIT1 / 0 (default)Whether to fully initialize XRay daemon for Lambda containers (may increase Lambda startup times)

    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 ).
    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_PG_CUSTOM_VERSIONS1 / (default)Whether to install and use custom Postgres versions for RDS (or alternatively, use default version 11).

    StepFunctions

    VariableExample ValuesDescription
    STEPFUNCTIONS_LAMBDA_ENDPOINTdefaultURL 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.

    SQS

    VariableExample ValuesDescription
    SQS_DELAY_RECENTLY_DELETED0 (default)Used to toggle QueueDeletedRecently errors when re-creating a queue within 60 seconds of deleting it.
    SQS_ENDPOINT_STRATEGYdomain|path|offConfigures the format of Queue URLs (see SQS Queue URLs)

    Security

    Emails

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

    VariableExample ValuesDescription
    SMTP_HOSTlocalhostHostname 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.

    Some of the services can be configured to switch to a particular provider:

    VariableValid optionsNotes
    KINESIS_PROVIDERkinesis-mock (default) and kinesalite
    KMS_PROVIDERmoto (default) and local-kms

    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:

    Here is an example of what a specific environment profile looks like

    You can load a profile by either setting the env variable CONFIG_PROFILE=<profile> or the --profile=<profile> CLI flag when using the CLI. Let’s take an example to load the dev.env profile file if it exists:

    To display the config environment variables, you can use the following command:

    Miscellaneous

    VariableExample ValuesDescription
    SKIP_INFRA_DOWNLOADSWhether to skip downloading additional infrastructure components (e.g., specific Elasticsearch versions)
    SKIP_SSL_CERT_DOWNLOADWhether to skip downloading the 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.
    EDGE_FORWARD_URLOptional target URL to forward all edge requests to (e.g., for distributed deployments)
    MOCK_UNIMPLEMENTEDWhether to return mocked success responses (instead of 501 errors) for currently unimplemented API methods
    DISABLE_EVENTS1Whether to disable publishing LocalStack events
    OUTBOUND_HTTP_PROXYHTTP 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
    DISABLE_TERM_HANDLERWhether to disable signal passing to LocalStack when running in docker. Enabling this will prevent an orderly shutdown when running inside LS in docker.

    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

    Additionally, the following read-only environment variables are available:

    • LOCALSTACK_HOSTNAME: Name of the host where LocalStack services are available. Use this hostname as endpoint (e.g., http://${LOCALSTACK_HOSTNAME}:4566) in order to access the services from within your Lambda functions (e.g., to store an item to DynamoDB or S3 from a Lambda).

    More information here.

    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_LOCAL_NAME_PATTERNSNames which should be resolved to the LocalStack IP, as python-compatible regex.

    LocalStack Pro

    More information here.

    VariableExample ValuesDescription
    LOCALSTACK_API_KEYAPI key to activate LocalStack Pro.
    LOG_LICENSE_ISSUES1 (default)Whether to log issues with the license activation to the console.
    REQUIRE_PRO0 (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.

    Read-only

    VariableUsage ExampleDescription
    LOCALSTACK_HOSTNAMEhttp://${LOCALSTACK_HOSTNAME}:4566Name 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).

    Deprecated