Filesystem Layout

This page describes the filesystem directory layout used internally by LocalStack.

Information

This filesystem layout was introduced in LocalStack v1 and can be disabled by setting to 1.

LocalStack uses following directories when running within a container.

  • /var/lib/localstack: the LocalStack volume directory root
  • /var/lib/localstack/lib: variable packages (like extensions or lazy-loaded third-party dependencies)
  • /var/lib/localstack/logs: logs for recent LocalStack runs
  • /var/lib/localstack/state: contains the state of services if persistence is enabled (such as OpenSearch cluster data)
  • /var/lib/localstack/cache: temporary data that is expected to survive LocalStack runs (is not cleared when LocalStack starts or stops)
  • /usr/lib/localstack: static third-party packages installed into the container images

Warning

DATA_DIR implicitly points to /var/lib/localstack/state if persistence is enabled. Use PERSISTENCE=1 to enable persistence. If DATA_DIR is set, its value is ignored, a warning is logged and PERSISTENCE is set to .

HOST_TMP_FOLDER is determined by inspecting the volume mounts and using the source of the bind mount to /var/lib/localstack.

For LocalStack to function correctly, the LocalStack volume must be mounted from the host into the container at /var/lib/localstack.

${LOCALSTACK_VOLUME_DIR} could be an arbitrary location on the host, e.g., ./volume. In this case, the effective layout would be something like:

  1. $ tree -L 4 ./volume
  2. .
  3. └── localstack
  4.     ├── cache
  5.     │   ├── machine.json
  6.     │   ├── server.test.pem
  7.     │   ├── server.test.pem.crt
  8.     │   └── server.test.pem.key
  9.     ├── lib
  11.     ├── logs
  12.     │   ├── localstack_infra.err
  13.     │   └── localstack_infra.log
  14.     ├── state
  15.     │   └── startup_info.json
  16.     └── tmp
  17.         └── zipfile.4986fb95

Using the CLI

When using the CLI to start LocalStack, the volume directory can be configured via the LOCALSTACK_VOLUME_DIR. It should point to a directory on the host which is then automatically mounted into /var/lib/localstack. The defaults are:

  • Mac: ~/Library/Caches/localstack/volume
  • Linux: ~/.cache/localstack/volume
  • Windows: %LOCALAPPDATA%/localstack/cache/volume

When LocalStack is running in host mode, the system directories /usr/lib/localstack or /var/lib/localstack are not used. Instead, the root directory is changed to FILESYSTEM_ROOT which defaults to , i.e. the LocalStack project root.