EnvPane - A macOS preference pane for environment variables

News

Release 0.8 is built for macOS 12 "Monterey" and up. It uses code-signed, universal binaries that run on Intel and Apple Silicon processors. It is not notarized by Apple and therefore requires special treatment during installation in order to work around quarantine.

What is it?

EnvPane is a preference pane for macOS that lets you set environment variables for all applications, both GUI and terminal. Not only does it restore support for ~/.MacOSX/environment.plist (seeBackground), it also publishes your changes to the environment immediately, without the need to log out and back in. This works for changes made by manually editing ~/.MacOSX/environment.plist as well via the preference pane UI.

EnvPane 0.8 was tested under macOS 12 "Monterey" on Apple Silicon and Intel.

EnvPane 0.6 was tested under OS X 10.09 "Mavericks", OS X 10.11 "El Capitan" and macOS Sierra (10.12). It should also work on 10.10 "Yosemite". Apple reimplemented launchd in 10.10 and in the course of doing so deprecated the APIs used by EnvPane and even broke some of them. EnvPane v0.6 adds support for the new but undocumented APIs, addressing the deprecation and broken APIs.

Caveats

EnvPane does not work for setting the PATH environment variable. See the FAQ on that topic.

EnvPane cannot be used to set DYLD_… variables. This is restriction imposed by macOS, I assume for security reasons.

While EnvPane is code-signed, it is not yet notarized by Apple. Lack of notarization means that it will be quarantined when downloaded by a web browser. macOS refuses to run quarantined binaries, displaying a mildly misleading error message. A user reports that, on Ventura, right-clicking the preference pane in Finder and selecting Open overrides that restriction. I was not able to confirm that workaround for Monterey (I haven't upgraded to Ventura yet). For details, refer to #34.

Download

The code-signed binary of EnvPane can bedownloaded from GitHub. Be sure to read the [installation instructions].

Alternatively you might want to grab the source and build it yourself.

Background

Mac OS X releases prior to Mountain Lion (10.8) included support for ~/.MacOSX/environment.plist, a file that contained session-global, per-user environment variables. Starting with Mountain Lion, support of this well-documented and popular mechanism was dropped without an official announcement or explanation by Apple. It may have been in [response] flashback to the Flashback trojan which used that file to inject itself into every process, but this is a wild guess, especially considering that there is a relatively easy workaround, as demonstrated by the existence of this very utility.

EnvPane includes (and automatically installs) a launchd agent that runs 1) early after login and 2) whenever the ~/.MacOSX/environment.plist changes. The agent reads ~/.MacOSX/environment.plist and exports the environment variables from that file to the current user's launchd instance via the same API that is used by launchctl setenv and launchctl unsetenv.

TODO: Mention /etc/launchd.conf and ~/.launchd.conf

Requirements

macOS 12 "Monterey" or higher.

For release 0.6, Mac OS X 10.9 "Mavericks" or higher.'

Installation

One liner

Run this command in Terminal to download and install EnvPane in a single step.

(cd ~/Library/PreferencePanes && rm -rf EnvPane.prefPane && curl -sL https://github.com/hschmidt/EnvPane/releases/download/releases%2F0.8/EnvPane-0.8.tar.bz2 | tar -xjf -)

Traditional installation

Download EnvPane-0.8.dmg
Run xattr -dr com.apple.quarantine ~/Downloads/EnvPane-0.8.dmg in Terminal
Double-click the downloadedEnvPane-0.8.dmg. A Finder window opens
Double-click the EnvPane.pref-pane file
Choose Install for this user only

Do not use the Install for all users option. See the FAQ.

Usage

When you open the Environment Variables preference pane, you will see a simple two-column table that lists the environment variables from your ~/.MacOSX/environment.plist. If that file doesn't exist, the table will be empty but the file will be created as soon as you add an entry to the table. To add an environment variable click the + button. Specify the name of the new variable, hit tab and specify its value. Hit enter. To modify a variable, click its name or value, make the desired changes and hit enter. To delete an environment variable, click a row in the table and click the - button.

Changes are effective immediately (after a delay of a few seconds) in all subsequently launched applications. There is no need to reboot or log out. However, running applications will [not be affected] (#why-arent-running-applications-affected). You need to quit and relaunch the application, in order for your changes to take effect.

The $ character in a value has special meaning. It induces the interpolation of other environment variables or the output of shell commands. If the $ character is followed by the name of another variable, e.g. $FOO the value of that variable will be inserted in place. The referenced variable can be one explicitly defined in the preference pane or it can be one from the default environment that launchd sets up. The variable name following $ must contain only letters, digits or underscore and may not start with a digit. To interpolate a variable whose name does not meet those requirements, place the variable name between curly braces, e.g. ${F-O-O}. You can also interpolate the name of an interpolated variable: assuming the variable EFF is set to the value F, ${${EFF}OO} would reference the variabe FOO. Don't worry if this looks confusing, this is an esoteric feature.

To interpolate the output of a shell command, enclose it in parentheses. $(date), for example, is replaced with the current date, because that's what the date program prints to standard output. The command is subject to shell expansion –because it is invoked via /bin/sh -c– but also to immediate variable interpolation by EnvPane as described above. In other words, $(BAR=bar ; echo $BAR) will not evaluate to bar because the $BAR reference will be interpolated by EnvPane, at a time when BAR is not yet defined. To prevent EnvPane from evaluating the reference, you must escape the dollar sign: $(BAR=bar; echo $$BAR).

Again, whenever you need a literal dollar sign in a variable value, you need do write two dollar signs: $$. If you need a closing parentheses inside a command interpolation, or a closing curly brace inside a variable interpolation, you need to write $() or ${} respectively. I now realize that $) and $} would have been a better choice but it is what it is.

Uninstallation

Open System Preferences
Right click Environment Variables
Select Remove Environment Variables Preference Pane

The uninstallation should be clean. I went to great lengths in ensuring that removing the preference pane doesn't leave orphaned files on the system. The ~/.MacOSX/environment.plist will not be removed.

Changelog

v0.8

Work around quarantine

v0.7

Code-signed with my Apple Developer ID
Universal binary (Apple Silicon and Intel)
Works in dark mode
Dealt with a few deprecations
Fixed a font color issue in dark mode

v0.6

Support for interpolation of other variables and shell command output
Support for macOS Sierra
Minor UI changes and a few bug fixes
Fix: Projects doesn't build with XCode 7 on OS X El Capitan (10.11)
Fix: envlib_unsetenv() is invoked unnecessarily with empty string if environment is empty (issue #3)

v0.5 and v0.4

Ignore. They are releases made from a fork of this repository, not by the original author and inauspiciously using the EnvPane name.

v0.3

Fix: Preference pane fails to load if ~/Library/LaunchAgents is missing (issue #2)

v0.2

Fix: Preference pane fails to load if ~/.MacOSX or ~/.MacOSX/environment.plist are missing (issue #1).

v0.1.1

Improved documentation.

v0.1

Initial release.

<a id="building-from-source"></a> Building from source

Build Requirements

Mac OS X 10.8, Mountain Lion
Xcode 4.5.x (I use 4.5.2)
A copy of Apple's launchd source tree, available on [Apple Open Source] apple_open_source under the Apache License 2.0. The current version of EnvPane was compiled against launchd-442.26.2
David Parsons' [Discount][discount] C library by for processing John Gruber's Markdown. Install the library as described on the project page. Using the default installation prefix of /usr/local is recommended. The current version of EnvPane was statically linked against version 2.2.1 of that library. HomeBrew users can use brew install discount to install it.

[disco

EnvPane

Install / Use

README