Skip to content

Filesystem Layout

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

LocalStack uses following directory layout when running within a container.

  • Directoryetc
    • Directorylocalstack
      • init
  • Directoryusr
    • Directorylib
      • localstack
  • Directoryvar
    • Directorylib
      • Directorylocalstack the LocalStack volume directory root
        • cache
        • lib
        • logs
        • state
        • tmp
  • /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/tmp: temporary data that is not expected to survive LocalStack runs (may be cleared when LocalStack starts or stops)
  • /var/lib/localstack/cache: temporary data that is expected to survive LocalStack runs (is not cleared when LocalStack starts or stops)
  • /etc/localstack: configuration directory
  • /etc/localstack/init: root directory for initialization hooks
  • /usr/lib/localstack: static third-party packages installed into the container images

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

When using Docker Compose, this can be achieved using following:

volumes:
- "${LOCALSTACK_VOLUME_DIR:-./volume}:/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:

  • Directorylocalstack
    • Directorycache
      • machine.json
      • server.test.pem
      • server.test.pem.crt
      • server.test.pem.key
    • Directorylib
      • Directoryopensearch
        • 1.1.0
    • Directorylogs
      • localstack_infra.err
      • localstack_infra.log
    • Directorystate
      • startup_info.json
    • Directorytmp
      • zipfile.4986fb95

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%\cache\localstack\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 ./.filesystem, i.e. the LocalStack project root.