The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: kraftbj <[email protected]>
Co-authored-by: ObliviousHarmony <[email protected]>
Co-authored-by: nerrad <[email protected]>
Co-authored-by: jsnajdr <[email protected]>
Co-authored-by: youknowriad <[email protected]>
Co-authored-by: mcsf <[email protected]>
Co-authored-by: andrewserong <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @kraftbj! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

Thanks for the thorough review! I've addressed the code-level feedback (loop refactor, structured port data instead of string messages, mocked tests, moving resolution into config parsing, dropping MySQL auto-resolution since it already works via Docker). Working through the port: null question now since I think it's worth discussing.

The existing mysqlPort: null pattern works well for MySQL because nothing inside the container needs to know the external MySQL port -- Docker picks one, and we read it back afterward. HTTP ports are different. WordPress needs the port baked into WP_SITEURL and WP_HOME before Docker starts. So we can't use the same "let Docker figure it out" approach for HTTP ports; we need to resolve the port ourselves, then pass it to the Docker config.

Given that, I think auto-by-default is the right call for the common case. The whole motivation behind #49843 is that developers run wp-env start, port 8888 is busy, and they have to stop and manually configure a different port. Making them opt into auto-resolution (even via null) adds a step most people won't know about until they hit the problem.

That said, I get the appeal of consistency with the null pattern -- it's a clear signal of intent. What if we default port and testsPort to null in the config (like mysqlPort already is), so the auto-resolution is the default behavior? Users who want a static port can set an explicit number. This way we get the null-means-auto pattern you're describing, AND it works out of the box without extra config.

The trade-off is that default ports become unpredictable (you'd get whatever's free instead of always 8888). For most developers that's fine -- they just want it to work. For anyone who needs a stable port (scripts, bookmarks, etc.), setting "port": 8888 is straightforward.

Thoughts on that approach?

The use case I'm running into is something along the lines of:

1. working on multiple projects that have wp-env setup to stand up the local development environment.
2. working in multiple worktrees on those projects.
3. reviewing PRs in those projects.

Yeah, I guessed that this was the motivation. It's a more common one nowadays, and indeed other colleagues have complained about poor ergonomics when trying to play with parallel "agents" working in different branches+envs.

This weekend I was goofing around with a tool for myself to take advantage of git worktrees with wp-env more seamlessly. I hope I can refine it this next weekend, but in meantime here's the relevant part: allocating a free port when creating a new worktree:

# ...

if ! test -d "$WORKTREE"; then
	# Need to set up a fresh worktree, but first ensure we find an available
	# HTTP port.
	if ! find "$WORKTREES" -path '*/.wp-env.override.json' | grep -q .; then
		PORT=9000
	else
		PORT=$(comm -13 \
			<(find "$WORKTREES" -path '*/.wp-env.override.json' -print0 \
				| xargs -0 jq .port | sort -g) \
			<(seq 9000 9100) \
			| grep -m1 .) || error "no ports available"
	fi

	# ...

	git worktree add "$WORKTREE" "$BRANCH"

	printf '{"port":%d,"phpmyadminPort":null}\n' "$PORT" > "$WORKTREE/.wp-env.override.json"
fi

cd "$WORKTREE"
# ... etc.

There's a bit of shell magic there (command substitution, my old friend comm…) but in short we lazily take the first port from a range of 9000–9100 that isn't already assigned in some .wp-env.override.json.

Anyway, this isn't meant to dismiss the need for --auto-port in wp-env, but indeed to validate the use case. :) In other words, both things can be true at the same time:

• Some envs are short-lived (when going in and out of a branch for one-off testing, when orchestrating scripts or agents, etc.)
• Developers have one or a couple of long-lived envs on which any branch can be checked out. Often, devs have specific posts, CPTs, plugins, themes, style settings, etc. that they intend to keep to test different features over time.

In other words, both things can be true at the same time

Indeed, I think that captures my immediate thoughts on this topic, too. For large feature development (e.g. media library work), I want a long-lived local dev environment as I've got things set up exactly as I want for that feature (100s of media items, large posts containing dozens of gallery blocks, etc, etc)

Whereas for quick bug fixes and testing PRs, I'll want an ephemeral environment.

Personally I like the idea of the default being the long-lived environment, and I like the general idea of the --auto-port flag as an opt-in 👍

I can dig the opt-in approach. I hadn't used wp-env for anything persistent, but I can completely understand where that would be handy. If I were designing wp-env from scratch today, I would probably say a persistent state would be the opt-in one, but I would argue strongly for not changing the default if I were already using it in that way. :-D

I've updated the branch to use --auto-port and ran through a manual test matrix covering both modes:

# Block a port (replace PORT):
python3 -c "
import socket, time
s4 = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s4.bind(('0.0.0.0', PORT)); s4.listen(1)
s6 = socket.socket(socket.AF_INET6, socket.SOCK_STREAM)
s6.bind(('::', PORT)); s6.listen(1)
print('Blocking PORT'); import sys; sys.stdout.flush()
while True: time.sleep(1)
" &

npm run wp-env start
npm run wp-env status  # expect port 8888
npm run wp-env stop

# Block 8888 (both IPv4+IPv6), then:
npm run wp-env start   # expect Docker bind error
# Kill blocker, stop env

echo '{ "port": 9100 }' > .wp-env.override.json
npm run wp-env start
npm run wp-env status  # expect port 9100
npm run wp-env stop
rm .wp-env.override.json

WP_ENV_PORT=9001 npm run wp-env start
npm run wp-env status  # expect port 9001
npm run wp-env stop

npm run wp-env start -- --auto-port
npm run wp-env status  # expect port 8888
npm run wp-env stop

# Block 8888, then:
npm run wp-env start -- --auto-port  # expect ephemeral port
npm run wp-env stop
# Kill blocker

# Block both 8888 and 8889, then:
npm run wp-env start -- --auto-port  # expect two distinct ephemeral ports
npm run wp-env stop
# Kill blockers

echo '{ "port": 9200 }' > .wp-env.override.json
# Block 9200, then:
npm run wp-env start -- --auto-port  # expect ephemeral fallback
npm run wp-env stop
# Kill blocker
rm .wp-env.override.json

echo '{ "port": null }' > .wp-env.override.json
# Block 8888, then:
npm run wp-env start -- --auto-port  # expect ephemeral fallback
npm run wp-env stop
# Kill blocker
rm .wp-env.override.json

npm run wp-env start -- --auto-port
npm run wp-env run cli wp option get siteurl  # expect matching port
npm run wp-env run cli wp option get home     # expect matching port
npm run wp-env stop

echo '{ "port": null }' > .wp-env.override.json
# Block 8888, then:
npm run wp-env start -- --auto-port
npm run wp-env run cli wp option get siteurl  # expect ephemeral port
npm run wp-env stop
# Kill blocker
rm .wp-env.override.json

npm run wp-env start -- --auto-port   # starts on 8888
npm run wp-env start -- --auto-port   # port shifts to ephemeral (known behavior)
npm run wp-env stop

echo '{ "testsEnvironment": false }' > .wp-env.override.json
npm run wp-env start -- --auto-port
npm run wp-env status  # no tests port
npm run wp-env stop
rm .wp-env.override.json

npm run test:unit -- --testPathPattern="packages/env"
# expect 18 suites, 138 tests, 8 snapshots all passing

If wp-env is intended more for production-esq instances—or instances that persist over time—then perhaps another tool is better for rapid development work?

I wouldn't say that wp-env is intended for production sites, quite the opposite, the intent is to "easily set up a local WordPress environment for building and testing plugins and themes" as the README says.

But the mainstream usage so far was to spin up the instance once and have it running long-term. What changes all the time is not the instance itself, but the plugin code inside the mapped directories. Gutenberg, CIAB Admin, Woo plugins etc.

Now, driven mainly with agents, the mainstream use case is shifting towards having multiple more ephemeral instances.

I did a little research on how Vite behaves when running a dev server. It's a tool with very similar purpose and problems.

• the default behavior is that if a port is already occupied, Vite will increment the port number by one until a free port is found.
• there is a --strictPort CLI flag, available also in a JSON config form, "strictPort": true that disables the auto-selection and fails quickly.
• an important details is to inform the user in detail about what is happening. In console, report that a port was tried, failed, now I'm trying another, and another, and finally started the server at http://localhost:8889. The current wp-env is good at reporting the final state, not sure about the in-progress state.
• even with auto-selection, you specify the port number. The meaning is "where to start".

Based on this, I think the following behavior of wp-env would be nice:

• always specify the port. The null value no longer means "auto-selection"
• add a new flag, --auto-port, both in CLI and JSON config, that enables the auto-selection. It would be disabled in CI, where it's unwanted
• when searching for available ports, start from the default one and increment. It feels much more orderly when I have a farm of dev servers running at 8888, 8889, 8890, 8891, ... instead of jumping somewhere to 49152

In Vite, the --auto-port mode is the default, but it's OK if we make it opt-in. I have no strong opinion about this.

Based on this, I think the following behavior of wp-env would be nice:

• always specify the port. The null value no longer means "auto-selection"
• add a new flag, --auto-port, both in CLI and JSON config, that enables the auto-selection. It would be disabled in CI, where it's unwanted
• when searching for available ports, start from the default one and increment. It feels much more orderly when I have a farm of dev servers running at 8888, 8889, 8890, 8891, ... instead of jumping somewhere to 49152

From that and @youknowriad's thumbs up on the comment, I'll make changes to match this.

Changes in this push:

• Removed null as a valid port value—ports always have an integer default now
• Added autoPort as a JSON config option (in .wp-env.json / .wp-env.override.json), alongside the existing --auto-port CLI flag
• Changed port scanning to increment from the configured port (e.g. 8888 → 8889 → 8890) instead of jumping to ephemeral range (49152+)

All previous tests were rerun and still pass. Updated/new test results:

python3 -c "
import socket, time
s4 = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s4.bind(('0.0.0.0', PORT)); s4.listen(1)
s6 = socket.socket(socket.AF_INET6, socket.SOCK_STREAM)
s6.bind(('::', PORT)); s6.listen(1)
while True: time.sleep(1)
" &

npm run test:unit -- --testPathPattern="packages/env"

I was hoping a rerun would resolve (can't do a rerun myself), but I rebased it to see if that would do it.

The unit test failure (packages/components/src/composite/legacy/test/index.tsx — toHaveFocus assertion) is unrelated to this PR, I think. The same shard passes on the latest trunk run, and there's a history of focus-timing flakiness in the Composite legacy tests.