Environment Variables

Environment Variables

This page documents the environment variables used in Lima.

LIMA_HOME

• Description: Specifies the Lima home directory.
• Default: ~/.lima
• Usage:
  shCopy

  export LIMA_HOME=~/.lima-custom
  lima
  

LIMA_INSTANCE

• Description: Specifies the name of the Lima instance to use.
• Default: default
• Usage:
  shCopy

  export LIMA_INSTANCE=my-instance
  lima uname -a
  

LIMA_SHELL

• Description: Specifies the shell interpreter to use inside the Lima instance.
• Default: User's shell configured inside the instance
• Usage:
  shCopy

  export LIMA_SHELL=/bin/bash
  lima
  

LIMA_TEMPLATES_PATH

• Description: Specifies the directories used to resolve template: URLs.
• Default: $LIMA_HOME/_templates:/usr/local/share/lima/templates
• Usage:
  shCopy

  export LIMA_TEMPLATES_PATH="$HOME/.config/lima/templates:/usr/local/share/lima/templates"
  limactl create --name my-vm template:my-distro
  

LIMA_WORKDIR

• Description: Specifies the initial working directory inside the Lima instance.
• Default: Current directory from the host
• Usage:
  shCopy

  export LIMA_WORKDIR=/home/user/project
  lima
  

LIMA_SHELLENV_ALLOW

• Description: Specifies a comma-separated list of environment variable patterns to exempt from the block list when propagating environment variables to the Lima instance with --preserve-env. Variables matching the allow list pass through even if they also match the block list. Variables that match neither list pass through as well. This feature only applies to Lima v2.0.0 or later.
• Default: unset (when using --preserve-env, all variables are propagated except those matching the block list patterns)
• Usage:
  shCopy

  # Pass FPATH and XAUTHORITY even though they are on the default block list
  export LIMA_SHELLENV_ALLOW="FPATH,XAUTHORITY,CUSTOM_*"
  limactl shell --preserve-env default
  
  # To propagate ONLY specific variables, block everything else first
  export LIMA_SHELLENV_BLOCK="*"
  export LIMA_SHELLENV_ALLOW="GITHUB_TOKEN,MY_*"
  limactl shell --preserve-env default
  

• Behavior:
  • Without --preserve-env: No environment variables are propagated (regardless of this setting)
  • With --preserve-env and LIMA_SHELLENV_ALLOW unset: All variables are propagated except those in the block list
  • With --preserve-env and LIMA_SHELLENV_ALLOW set: Variables matching the allow list are propagated even if they also match the block list. Variables matching neither list are still propagated. Only variables that match the block list without a corresponding allow list match are blocked.
• Note: Patterns support * wildcards anywhere in the pattern (e.g., CUSTOM_* matches CUSTOM_VAR; *TOKEN* matches GITHUB_TOKEN).

LIMA_SHELLENV_BLOCK

• Description: Specifies a comma-separated list of environment variable patterns to block when propagating environment variables to the Lima instance with --preserve-env. Can either replace the default block list or extend it by prefixing with +. This feature only applies to Lima v2.0.0 or later.

• Default: A predefined list of system and shell-specific variables that should not be propagated:

  • Shell variables: BASH*, SHELL, SHLVL, ZSH*, ZDOTDIR, FPATH
  • System paths: PATH, PWD, OLDPWD, TMPDIR
  • User/system info: HOME, USER, LOGNAME, UID, GID, EUID, GROUP, HOSTNAME
  • Display/terminal: DISPLAY, TERM, TERMINFO, XAUTHORITY, XDG_*
  • SSH/security: SSH_*
  • Dynamic linker: DYLD_*, LD_*
  • Internal variables: _* (variables starting with underscore)

  See GetDefaultBlockList() for the complete list.

• Usage:

  shCopy

  # Replace default block list entirely (not recommended)
  export LIMA_SHELLENV_BLOCK="SECRET_*,PRIVATE_*"
  
  # Extend default block list (recommended)
  export LIMA_SHELLENV_BLOCK="+SECRET_*,PRIVATE_*"
  limactl shell --preserve-env default
  

• Note: Patterns support * wildcards anywhere in the pattern (e.g., SSH_* matches SSH_AUTH_SOCK; *TOKEN* matches GITHUB_TOKEN). Use the + prefix to add to the default block list rather than replacing it entirely. This variable only affects the --preserve-env flag behavior.

LIMACTL

• Description: Specifies the path to the limactl binary.
• Default: limactl in $PATH
• Usage:
  shCopy

  export LIMACTL=/usr/local/bin/limactl
  lima
  

LIMA_SSH_OVER_VSOCK

• Description: Specifies to use vsock for SSH connection instead of port forwarding.
• Default: true (since v2.0.0)
• Usage:
  shCopy

  export LIMA_SSH_OVER_VSOCK=true
  

• Note: This variable is effective only if the VM is VZ based and systemd is v256 or later (e.g. Ubuntu 24.10+).
• Deprecated: This variable is deprecated in favor of the YAML field .ssh.overVsock (since v2.0.2).

LIMA_SSH_PORT_FORWARDER

• Description: Specifies to use the SSH port forwarder (slow) instead of gRPC (fast, previously unstable)
• Default: false (since v1.1.0)
• Usage:
  shCopy

  export LIMA_SSH_PORT_FORWARDER=false
  

• The history of the default value:

  Version	Default value
  v0.1.0	true, effectively
  v1.0.0	false
  v1.0.1	true
  v1.1.0	false

LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT

• Description: Specifies the timeout duration for resolving the IP address in usernet.
• Default: 2 minutes
• Usage:
  shCopy

  export LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT=5
  

_LIMA_QEMU_UEFI_IN_BIOS

• Description: Commands QEMU to load x86_64 UEFI images using -bios instead of pflash drives.
• Default: false on Unix like hosts and true on Windows hosts (if QEMU is older than 11.0.0)
• Usage:
  shCopy

  export _LIMA_QEMU_UEFI_IN_BIOS=true
  

• Note: This variable is deprecated and is expected to be removed, when minimal supported QEMU version on Windows is adjusted.

_LIMA_WINDOWS_EXTRA_PATH

• Description: Additional directories which will be added to PATH by limactl.exe process to search for tools. It is useful, when there is a need to prevent collisions between binaries available in active shell and ones used by limactl.exe - injecting them only for the running process w/o altering PATH observed by user shell. Is is Windows specific and does nothing for other platforms.
• Default: unset
• Usage:
  batCopy

  set _LIMA_WINDOWS_EXTRA_PATH=C:\Program Files\Git\usr\bin
  

• Note: It is an experimental setting and has no guarantees being ever promoted to stable. It may be removed or changed at any stage of project development.

QEMU_SYSTEM_AARCH64

• Description: Path to the qemu-system-aarch64 binary.
• Default: qemu-system-aarch64 found in $PATH
• Usage:
  shCopy

  export QEMU_SYSTEM_AARCH64=/usr/local/bin/qemu-system-aarch64
  

QEMU_SYSTEM_ARM

• Description: Path to the qemu-system-arm binary.
• Default: qemu-system-arm found in $PATH
• Usage:
  shCopy

  export QEMU_SYSTEM_ARM=/usr/local/bin/qemu-system-arm
  

QEMU_SYSTEM_PPC64

• Description: Path to the qemu-system-ppc64 binary.
• Default: qemu-system-ppc64 found in $PATH
• Usage:
  shCopy

  export QEMU_SYSTEM_PPC64=/usr/local/bin/qemu-system-ppc64
  

QEMU_SYSTEM_RISCV64

• Description: Path to the qemu-system-riscv64 binary.
• Default: qemu-system-riscv64 found in $PATH
• Usage:
  shCopy

  export QEMU_SYSTEM_RISCV64=/usr/local/bin/qemu-system-riscv64
  

QEMU_SYSTEM_S390X

• Description: Path to the qemu-system-s390x binary.
• Default: qemu-system-s390x found in $PATH
• Usage:
  shCopy

  export QEMU_SYSTEM_S390X=/usr/local/bin/qemu-system-s390x
  

QEMU_SYSTEM_X86_64

• Description: Path to the qemu-system-x86_64 binary.
• Default: qemu-system-x86_64 found in $PATH
• Usage:
  shCopy

  export QEMU_SYSTEM_X86_64=/usr/local/bin/qemu-system-x86_64