Auto-generated `.envrc` pollutes shell environment, breaking external CLI tools (e.g. Terminus/Pantheon)

[taupecat]

Bug Summary

Local’s auto-generated .envrc exports PHPRC and MAGICK_CODER_MODULE_PATH into the shell environment via direnv, causing any external PHP-based CLI tool (e.g. Terminus, Pantheon’s CLI) to load Local’s PHP configuration instead of the system PHP configuration, resulting in extension load failures and broken network connectivity.

Steps to reproduce

1. Install direnv and configure its shell hook ( Setup | direnv )
2. Start a Local site — Local auto-generates a .envrc file in the site directory
3. cd into the site directory (direnv automatically loads .envrc into the shell environment)
4. Run any external PHP-based CLI tool — in my case, terminus env:clear-cache <sitename.env>

Environment Info

• OS: macOS 26.5.1 (Tahoe)
• Local version: Version 10.1.1+6939
• Site PHP: 8.3.30
• System PHP (Homebrew): 8.5.7
• Web server: nginx
• MySQL: 8.0.35

Supporting info

The root cause: Local’s .envrc sets PHPRC to Local’s PHP configuration directory. When an external tool invokes system PHP (8.5), it loads Local’s php.ini, which references extensions compiled for PHP 8.3. This produces errors like:

Failed loading opcache.so: symbol not found in flat namespace '_zend_observer_fcall_end'
Xdebug requires Zend Engine API version 420230831. The version 420250925 which is installed is newer.
Warning: Unable to load dynamic library 'imagick.so'

These extension failures corrupt PHP’s runtime and break outbound HTTP — producing “Connection refused” errors against external APIs with no indication that a PHP misconfiguration is the cause.

Workaround: A wrapper script that clears the offending variables before invoking the external tool:

#!/bin/zsh
env PATH="/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin" \
    PHPRC="" \
    MAGICK_CODER_MODULE_PATH="" \
    /opt/homebrew/bin/terminus "$@"

Suggested fix: PHPRC and MAGICK_CODER_MODULE_PATH should not be exported into the general shell environment. These variables are only meaningful within Local’s own PHP runtime. Scoping them to Local’s internal WP-CLI context only would prevent them from leaking into the developer’s interactive shell and breaking other tools.

At minimum, the .envrc feature’s documentation should warn direnv users of this side effect. At MINIMUM minimum, creating a .envrc / using direnv should be able to be disabled through the preferences.

[nickc]

Thanks for your feedback, @taupecat, it’s helpful!

I’ve shared this with the Local team to help us consider options for a future release.

(We likely can’t omit PHPRC entirely as you propose because wp or php invoked from the site dir after direnv runs won’t use the correct php.ini. But we can explore other options that stop global var pollution, such as a PHP wrapper script that loads those vars before invoking PHP.)

[taupecat]

I just wanted to follow up on this…

This new .envrc file is wreaking all sorts of havoc on my set up, with no way to turn it off other than uninstalling direnv.

The latest wrinkle is that I have a composer-managed site with WordPress core in a subdirectory. I’ve just accepted the fact that Local doesn’t really “support” WP in a subdirectory, and gotten used to the “WordPress version” indicator never resolving and just blinking endlessly. (It would be SOOO nice if Local actually read and honored my wp-cli.yml file, but I digress…)

But now with .envrc + direnv, Local can’t find the WordPress cert when I run composer install, so it returns all sorts of ugly error messages.

I’ve just uninstalled direnv, and hopefully that means the .envrc file will be ignored and I won’t lose any more time debugging the issues it’s causing. I can just go back to setting the path of mysqld.sock manually in a wp-config-local.php file, which has worked for me for literally years and I see no reason to muck with it now.

[nickc]

We added the option to disable direnv in Local 10.1.2:

https://localwp.com/releases/10.1.2

Disable the “Direnv support” option under Preferences → Advanced to stop Local from writing new direnv files when you start your sites. (You will have to remove any existing direnv files created previously that you no longer want.)

[taupecat]

Thank you!