AWS configuration files, explained

I see a lot of people who aren’t fully aware of the difference between ~/.aws/config and ~/.aws/credentials. While it is more or less fine to just use one or the other, I think it’s worth understanding their intended purpose. So here’s a short explainer.

The idea is that ~/.aws/config is the main file, where you create profiles with the region, output format, and non-sensitive setup, like a profile that assumes a role based on another profile, an AWS SSO-authenticated profile, or a credential process. It’s a file you can (and maybe should) commit to source control.

~/.aws/credentials, on the other hand, is for secrets. Access key + secret key. Maybe a session token if you’ve got some temporary credentials you want to use, but you’re probably better off putting those in env vars since they’re temporary anyway.

You can use both; when the CLI or SDK is loading configuration, they get combined, with values from credentials taking precedence. You can set your region to us-east-2 and your output to yaml in ~/.aws/config and keep your keys in ~/.aws/credentials. But why do this, instead of just always using one or the other for everything? For me, the answer is that I do want ~/.aws/config to be a source-control-ready, publicly shareable file, because I keep it versioned along with other dotfiles. Having the shadow ~/.aws/credentials with any actual long-term secrets lets me do that without a security risk.

Note that the two files have slightly different header formats. In both files, the default profile section header is [default]. But for named profiles, in ~/.aws/config, the section header is [profile PROFILE_NAME], whereas in ~/.aws/credentials the header is just [PROFILE_NAME].

A slight tangent: you can have a default profile, but I actually recommend avoiding it. If you’ve got multiple accounts and/or identities, you’re going to have a lot of profiles, and it’s better that, if you haven’t set the profile as you expected to, you get an error rather than silently using the wrong credentials. If I’ve forgotten to set the profile, I’d rather aws s3 ls s3://mybucket tell me “Unable to locate credentials” than “Access Denied” or “No such bucket”.

If you’re interested in a utility to manage the currently-active profile in a shell, I’ve got a GitHub gist for that. If you want to know what the identity of the currently-active credentials are, you can use the CLI’s aws sts get-caller-identity or my more comprehensive aws-whoami tool.

Finally, the location of both of these files is configurable through environment variables. Change the location for config with AWS_CONFIG_FILE, and credentials with AWS_SHARED_CREDENTIALS_FILE.

Questions? Hit me up on Twitter.

Update: James Saryerwinnie, author of much of the code underlying this whole thing, provided some of the backstory on how this came to be!

Cloud Robotics Research Scientist at @iRobot

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store