wp-env statusnow reports the development URL based on the live Docker port mapping instead of the configuredWP_SITEURL. This fixes a stale URL when--auto-portreassigns the port; consumers readingurls.developmentfromwp-env status --jsonno longer have to fall back to constructing the URL fromports.developmentthemselves.
- Fix WP-Cron, REST API loopback, and Site Health loopback failures when wp-env runs on a non-default port. Apache inside the WordPress container now also listens on the host-mapped port, so PHP loopback requests to
WP_HOMEsucceed instead of being refused. (#20569)
- Suppress spinner and success message output when using
--jsonflag to ensure clean, parseable JSON output.
- Playground runtime now supports zip archive themes, matching Docker runtime behavior. (#75140).
- Add MySQL healthcheck to prevent race condition where WordPress containers start before MySQL is fully initialized. Uses MariaDB's official
healthcheck.shscript withMARIADB_AUTO_UPGRADEto support both new and existing installations. - Remove non-functional
WP_ENV_MULTISITEconfig.
- Added
--auto-portflag to thestartcommand. When passed,wp-envautomatically finds available ports if the configured ports are busy. Without this flag, ports default to8888/8889and Docker reports an error if they are busy (matching pre-existing behavior).
- Pretty permalinks (
/%year%/%monthnum%/%day%/%postname%/) are now enabled by default, matching WordPress core behavior on fresh installs. Previously, plain permalinks were used because the loopback test that WordPress runs during installation fails inside Docker. - The
portoption now defaults tonull(auto-select) instead of8888. Whennull,wp-envtries port 8888 (or 8889 for tests) first, then falls back to an available ephemeral port. Set an explicit port number to preserve the previous behavior. - Replaced
install-pathcommand withstatuscommand. The work directory path is now available as part of the status output.
- Added
phpmyadminboolean configuration option to enable phpMyAdmin. SettingphpmyadminPortalso enables phpMyAdmin for backward compatibility. - Added phpMyAdmin support to the Playground runtime. When enabled, phpMyAdmin is available at
http://localhost:<port>/phpmyadmin. - Added
statuscommand that shows comprehensive environment information including running state, URLs, ports, configuration, and paths. - Added
--configglobal option to specify a custom configuration file path, enabling multiple parallel environments from the same directory. - Added
testsEnvironmentconfiguration option. Set tofalseto skip creating test containers (tests-mysql,tests-wordpress,tests-cli,tests-phpmyadmin), reducing resource usage when test isolation is achieved via separate config files.
- Add experimental WordPress Playground runtime support. Use
--runtime=playgroundflag to start wp-env with Playground instead of Docker. - Add
cleanupcommand to remove environment-specific resources (containers, volumes, networks, and local files) while preserving Docker images for faster re-starts. - Add
--forceflag to bothdestroyandcleanupcommands to skip the confirmation prompt. - Rename
cleancommand toresetfor clarity. Thecleancommand is now deprecated but still works as an alias.
- The
cleancommand is deprecated. Useresetinstead. TheafterCleanlifecycle script is also deprecated in favor ofafterReset.
- Add config file for WP-CLI when creating an environment. (#70661).
- Add a
WP_ENV_MULTISITEenvironment variable to override themultisiteoption (#68792).
- Add support for WordPress multisite installations. Enabled via the new
multisiteenvironment config (#67845).
- Refactored the code to use new API introduced together with
@inquirer/promptsinstead of legacyinquirerpackage (#67877).
- Add phpMyAdmin as an optional service. Enabled via the new
phpmyadminPortenvironment config, as well as env varsWP_ENV_PHPMYADMIN_PORTandWP_ENV_TESTS_PHPMYADMIN_PORT(#67588).
- The bundled
rimrafdependency has been updated from^3.0.2to^5.0.10(#67708).
- Remove
versionfield from docker-compose config generated by env package #63099. Docker has starting throwing a warning that this property is obsolete and should be removed.
- Ignore
$schemakey in environment config parsing (#62626).
- Increase the minimum required Node.js version to v18.12.0 matching long-term support releases (#31270). Learn more about Node.js releases.
- Fix
mariadbversion to LTS #59237
- Update Docker usage to
docker composeV2 following deprecation ofdocker-composeV1.
wp-envnow works offline after the environment has been created. Note that manywp-envconfiguration changes involve internet connectivity and may not work in offline mode. #53547
- Corrected
PATHto include the host user's Composer bin directory. - Replaced
yoast/phpunit-polyfillswithphpunit/phpunitto install the required PHPUnit version, avoiding the need for project-specific polyfills.
- Address issue where a missing file in the underlying Docker image caused
wp-envto crash. #51513
- Execute the local package's
wp-envinstead of the globally installed version if one is available.
- Run
useraddwith-loption to prevent excessive Docker image sizes.
- Remove
afterSetupoption from.wp-env.jsonand theWP_ENV_AFTER_SETUPenvironment variable in favor of more granular lifecycle scripts.
- Add
afterStart,afterClean, andafterDestroylifecycle scripts to a newlifecycleScriptskey in.wp-env.json. - Add a series of
WP_ENV_LIFECYCLE_SCRIPT_environment variables for the various lifecycle scripts. - Rework
runcommand to resolve bugs with non-quoted commands. As a consequence it is no longer possible to pass your entire command towp-envwrapped in double-quotes. Whilenpx wp-env run cli wp helpwill still work,npx wp-env run cli "wp help"will not. If you are currently escaping any quotes you will need to review those commands and ensure they are compatible with this update.
- Support using double dashes in
wp-env run ...to pass arguments that would otherwise be consumed bywp-env. For example, while normally--helpwould provide thewp-envhelp text, if you usenpx wp-env run cli php -- --helpyou will see the PHP help text. - Validate whether or not config options exist to prevent accidentally including ones that don't.
- Support Windows without requiring the use of WSL.
- Docker containers now run as the host user. This should resolve problems with permissions arising from different owners between the host, web container, and cli container. If you still encounter permissions issues, try running
npx wp-env destroyso that the environment can be recreated with the correct permissions. - Remove the
composerandphpunitDocker containers. If you are currently using therun composerorrun phpunitcommand you can migrate torun cli composerorrun tests-cli phpunitrespectively. Note that withcomposer, you will need to use the--env-cwdoption to navigate to your plugin's directory as it is no longer the default working directory.
- Create an
afterSetupoption in.wp-env.jsonfiles for setting arbitrary commands to run after setting up WordPress when usingnpx wp-env startandnpx wp-env clean. - Add a
WP_ENV_AFTER_SETUPenvironment variable to override theafterSetupoption. - Execute the
afterSetupcommand onnpx wp-env startafter the environment is set up. This can happen when your config changes, WordPress updates, or you pass the--updateflag. - Execute the
afterSetupcommand onnpx wp-env clean. - Globally install
composerand the correct version ofphpunitin all of the Docker containers.
- Ensure
wordpress,tests-wordpress,cli, andtests-clialways build the correct Docker image. - Fix Xdebug while using PHP 7.2x.
wp-env run ...now uses docker-compose exec instead of docker-compose run. As a result, it is much faster, since commands are executed against existing services, rather than creating them from scratch each time.- Increase the maximum upload size to 1GB.
- Use test environment's
WP_SITEURLinstead ofWP_TESTS_DOMAINas the WordPress URL. - Automatically add the environment's port to
WP_TESTS_DOMAIN. runcommand now has a--env-cwdoption to set the working directory in the container for the command to execute from.
- PHP 7.3 and 7.4 must use PHPUnit 9.
- It's now possible to run PHPUnit tests on PHP 8.1 and 8.2.
- Query parameters can now be used in .zip source URLs.
- Fix a crash when "core" was set to
nullin a.wp-env.jsonfile. We now use the latest stable WordPress version in that case. This also restores the previous behavior of"core": nullin.wp-env.override.json, which was to use the latest stable WordPress version.
- Previously, wp-env used the WordPress version provided by Docker in the WordPress image for installations which don't specify a WordPress version. Now, wp-env will find the latest stable version on WordPress.org and check out the https://github.com/WordPress/WordPress repository at the tag matching that version. In most cases, this will match what Docker provides. The benefit is that wp-env (and WordPress.org) now controls the default WordPress version rather than Docker.
- Downloading a default WordPress version also resolves a bug where the wrong WordPress test files were used if no core source was specified in wp-env.json. The current trunk test files were downloaded rather than the stable version. Now, the test files will match the default stable version.
- Removed the
WP_PHPUNIT__TESTS_CONFIGenvironment variable from thephpunitcontainer. This removes automatic support for thewp-phpunit/wp-phpunitComposer package. To continue using the package, set the following two environment variables in yourphpunit.xmlfile or similar:WP_TESTS_DIR=""andWP_PHPUNIT__TESTS_CONFIG="/wordpress-phpunit/wp-tests-config.php". - Removed the generated
/var/www/html/phpunit-wp-config.phpfile from the environment.
- Read WordPress' version and include the corresponding PHPUnit test files in the environment.
- Set the
WP_TESTS_DIRenvironment variable in all containers to point at the PHPUnit test files.
- Restrict
WP_TESTS_DOMAINconstant to just hostname rather than an entire URL (e.g. it now excludes scheme, port, etc.) (#41039).
- Removed the need for quotation marks when passing options to
wp-env run. - Setting a
configkey tonullwill prevent adding the constant towp-config.phpeven if a default value is defined bywp-env.
- Added SSH protocol support for git sources
- Added command
wp-env install-pathto list the directory used for the environment. - The help entry is now shown when no subcommand is passed to
wp-env.
- Updated
yargsto fix CVE-2021-3807.
- Fix Xdebug installation code to ensure it would fail gracefully
wp-env destroywill now work in environments which don't include thegreporawkcommands, such as Windows PowerShell.- Fix several permissions issues related to wp-config.php and wp-content files.
- Fix crash which happened when the path to wp-env's home directory contained a space.
- Disable Xdebug 3 for PHP versions less than 7.2 to resolve startup crash.
- Migrate from
nodegittosimple-git. This change now requires you to have agitbinary installed locally to utilize the git sources feature of wp-env.json.
- "mappings" sources are now downloaded if they contain non-local sources.
wp-env startis now the only command which writes to the docker configuration files. Previously, running any command would also parse the config and then write it to the correct location. Now, other commands still parse the config, but they will not overwrite the configuration which was set by wp-env start. This allows parameters to be passed to wp-env start which can affect the configuration.
- Update nodegit dependency to 0.27.0, the earlier version does not have pre-built binaries for Node 14.15.0 LTS. Upgrading provides support without requiring building nodegit locally.
- Allow WP_HOME wp-config value to be set to a custom port other than the default for the docker instance.
- Append the instance URL to output of
wp-env start.
- Add support for setting the PHP version used for the WordPress instance. For example, test PHP 8 with
"phpVersion": 8.0in wp-env.json. - Add Xdebug 3 to the development environment. You can enable Xdebug with
wp-env start --xdebug(for debug mode) orwp-env start --xdebug=develop,coveragefor custom modes.
- ZIP-based plugin sources are now downloaded to a directory using the basename of the URL instead of the full URL path. This prevents HTML encoded characters in the URL (like "/") from being improperly encoded into the filesystem. This fixes the issue where many .zip sources broke because files with these badly formatted characters were not loaded as assets.
- The
configandmappingsoptions in.wp-env.jsonare now merged with any overrides instead of being overwritten. - The first listed theme is no longer activated when running wp-env start, since this overwrote whatever theme the user manually activated.
wp-env startno longer stops the WordPress instance if it was already started unless it needs to configure WordPress.wp-env startno longer updates remote sources after first install if the configuration is the same. Usewp-env start --updateto update sources.
- You may now specify specific configuration for different environments using
env.testsorenv.developmentin.wp-env.json. wp-env startis significantly faster after first install.
wp-env destroynow removes dangling docker volumes and networks associated with the WordPress environment.
- Add support for running interactive commands. Examples:
wp-env run cli wp shellandwp-env run cli bash. - View php and WordPress log output with the new
wp-env logscommand. - Clean up your local environment with the new
wp-env destroycommand. - Expose Docker service for running phpunit commands.
- You may now mount local directories to any location within the WordPress install. For example, you may specify
"wp-content/mu-plugins": "./path/to/mu-plugins"to add mu-plugins.
- URLs for ZIP files are now supported as core, plugin, and theme sources.
- The
.wp-env.jsonconiguration file now accepts aconfigobject for settingwp-config.phpvalues. - A
.wp-env.override.jsonconfiguration file can now be used to override fields from.wp-env.json. - You may now override the directory in which
wp-envcreates generated files with theWP_ENV_HOMEenvironment variable. The default directory is~/.wp-env/(or~/wp-env/on Linux). - The
.wp-env.jsonconiguration file now acceptsportandtestsPortoptions which can be used to set the ports on which the docker instance is mounted.
wp-env startno longer accepts a WordPress branch or tag reference as its argument. Instead, create a.wp-env.jsonfile and specify a"core"field.wp-env startwill now download WordPress into a hidden directory located in~/.wp-env. You may delete your{projectName}-wordpressand{projectName}-tests-wordpressdirectories.
- A
.wp-env.jsonconfiguration file can now be used to specify the WordPress installation, plugins, and themes to use in the local development environment.
- When running scripts using
wp-env run, the output will not be formatted if not written to terminal display, resolving an issue where piped or redirected output could be unintentionally padded with newlines.