Set Environment Variable for Applications on Startup in MacOS

environment-variableshigh sierralaunchdmacos

How do you set an environment variable on startup so that it can be used in applications?

For example, ATOM_HOME is used by Atom.

Best Answer

Solution

The solution uses two files: environment.plist and environment.conf.

environment.plist should be placed in ~/Library/LaunchAgents for a per user solution (recommended), or in /Library/LaunchAgents for a global solution (not recommended – potential security loophole).

environment.conf can be placed almost anywhere. $PATH_TO_ENVIRONMENT_CONF can be relative, but only to the 'default' environment variables, or any that are defined in a EnvironmentVariables key. ¹

environment.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>local.launchd.environment</string>
  <key>ProgramArguments</key>
  <array>
    <string>sh</string>
    <string>-c</string>
    <string>xargs -L 1 launchctl &lt; $PATH_TO_ENVIRONMENT_CONF</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

environment.conf:

setenv ATOM_HOME $HOME/.config/atom
setenv SOME_VAR "Use quotes if spaces are necessary"

How it works

When a user logs in, the LaunchAgents in ~/Library/LaunchAgents are executed. In this case, sh -c xargs -L 1 launchctl < $PATH_TO_ENVIRONMENT_CONF is executed. launchctl manages daemons and agents. In this case, we are using it to set an environment variable accessible to all applications and the shell.

xargs -L 1 launchctl &lt; $PATH_TO_ENVIRONMENT_CONF

xargs                     # xargs converts stdin to command line arguments
xargs -L 1                # Tells xargs to invoke launchctl for each line
           launchctl      # Run launchctl with the arguments
                     &lt; # Since a plist is an xml document, angle brackets must be escaped. 

                     &lt; $PATH_TO_ENVIRONMENT_CONF
                          # This tells xargs to read input from the file at $PATH_TO_ENVIRONMENT_CONF

This solution can also be extended to other launchctl subcommands.

Notes for set-up of shells:

For correct functioning in local shells it is important to switch off the use of /usr/libexec/path_helper, because the default paths in /etc/paths might change the order of the paths in PATH.**
To accommodate remote shells you need to re-import the launchd environment into the shell. Use something like this in your .bashrc:

# the vexatious path stuff
eval $(launchctl export)

Unfortunate consequences of the whole issue are:

No way to have these unified settings on a per user basis. (~/.launchd.conf does not work.)
No easy way to construct the PATH from different sources using techniques like home directory expansion et al.

MacOS Environment Variables – Setting the System-wide PATH in Mavericks

Yosemite

/etc/launchd.conf is no longer supported in 10.10. See man launchctl:

The /etc/launchd.conf file is no longer consulted for subcommands to run during early boot time; this functionality was removed for security considerations.

You can now for example save this plist as ~/Library/LaunchAgents/my.startup.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>my.startup</string>
  <key>ProgramArguments</key>
  <array>
    <string>sh</string>
    <string>-c</string>
    <string>launchctl setenv PATH /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

The launchctl setenv command is ran as the user, so it only applies to processes launched in the user domain.

This method doesn't apply to applications that are reopened at login if "Reopen windows when logging back in" is checked.

Mavericks and earlier

In 10.9 and earlier, you can for example run

echo setenv PATH /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin|sudo tee -a /etc/launchd.conf

and then restart to apply the changes.

Other methods

/etc/paths and /etc/paths.d/ apply only (or mainly) to shells. The lines in /etc/paths and /etc/paths.d/* are added to the path by path_helper, which is run from /etc/profile, /etc/zshenv, and /etc/csh.login. I don't know any programs other than shells that would consider /etc/paths or /etc/paths.d/.

~/.MacOSX/environment.plist stopped working in 10.8.