Where Do SOPS Config and Age Keys Live?
SOPS reads creation rules from .sops.yaml at the repo root and age keys from the OS config dir.
Last updated
SOPS splits its file story two ways. Creation rules (which keys encrypt which files) live in .sops.yaml, searched upward from your current working directory, first match wins per path_regex. Decryption identities for age live in keys.txt under a sops/age folder in the OS config dir: ~/.config on Linux, Application Support on macOS, %APPDATA% on Windows.
Two gotchas dominate support threads. The config filename ends in .yaml, and .yml silently does nothing. And lookup starts at the working directory rather than the file being encrypted, so running sops from the wrong folder applies the wrong rules. CLI flags and env vars override the file when they disagree.
Where SOPS stores this, by platform
~/.config/sops/age/keys.txt
keys.txt with age identities. Creation rules in .sops.yaml at the repo root. SOPS_AGE_KEY_FILE, SOPS_AGE_KEY, and SOPS_AGE_KEY_CMD override lookup.
~/Library/Application Support/sops/age/keys.txt
Same keys.txt layout. XDG_CONFIG_HOME respected when set. Same .sops.yaml discovery from the working directory.
%APPDATA%\sops\age\keys.txt
Same keys.txt role under Roaming. Same repo-root .sops.yaml discovery.
Frequently asked questions
SOPS ignores my config file. What is wrong?
It must be named exactly .sops.yaml in an ancestor of your working directory. .sops.yml is never auto-discovered; pass it explicitly with --config if you insist on the shorter name.
How do I use an age key outside the default location?
SOPS_AGE_KEY_FILE for a custom path, SOPS_AGE_KEY for inline keys, or SOPS_AGE_KEY_CMD for a command that prints them. The env vars beat the default lookup, which is how CI and shared machines stay sane.
Notice an outdated path? Let us know.