Creating IPv4-only and IPv6-only containers with podman

By default, newer versions of podman run containers with a dual stack network that supports IPv4 and IPv6 (yay). But if you're doing something specific, you can set up IPv4-only and IPv6-only networks.

(Note: I tested this all with rootless podman 5.5.0, the current version in Fedora 42.)

I'm primarily writing this because it took me a while to figure this out, I got entirely tripped up by the --ipv6 option which turned out to not be what I wanted, despite the name implying it enables IPv6.

The documentation for it is technically accurate, as it says:

Enable IPv6 (Dual Stack) networking. If no subnets are given, it allocates an ipv4 and an ipv6 subnet.

The most important part is in parenthesis — it enables a dual-stack network. Which means that passing --ipv6 when creating a network doesn't just enable IPv6, it also enables IPv4!

Real IPv6-only#

What you actually want is:

$ podman network create --subnet fd00::/64 --gateway fd00::1 ipv6-only

You can verify that IPv4 doesn't work by:

$ podman pull quay.io/curl/curl:latest
$ podman run --rm -it --net=ipv6-only curl -v4 https://en.wikipedia.org
* Host en.wikipedia.org:443 was resolved.
* IPv6: (none)
* IPv4: 208.80.154.224
*   Trying 208.80.154.224:443...
* Immediate connect fail for 208.80.154.224: Network unreachable
* Failed to connect to en.wikipedia.org port 443 after 13 ms: Could not connect to server
* closing connection #0
curl: (7) Failed to connect to en.wikipedia.org port 443 after 13 ms: Could not connect to server

And that IPv6 works:

$ podman run --rm -it --net=ipv6-only curl -I6 https://en.wikipedia.org
HTTP/2 301 
date: Fri, 23 May 2025 00:29:41 GMT
...

IPv4-only#

And now for IPv4, which is even simpler:

$ podman network create ipv4-only

Yep, no options needed, you just need a network in which IPv6 is not enabled by the subnet and doesn't pass the --ipv6 flag.

Final notes#

The default networking stack for rootless containers is documented (under "pasta") as "IPv4 and IPv6 addresses and routes, as well as the pod interface name, are copied from the host". In my testing this is correct, but this is an entirely separate thing from podman network that appears to exist by default, which is IPv4-only.

I ended up figuring out the whole misleading --ipv6 thing thanks to a GitHub comment, which explicitly spelled out "The --ipv6 flags means dual-stack", and even explained the rationale why: "this is fully compatible with docker ..."

I shouldn't be too surprised that Claude also got tripped up by the --ipv6 flag and gave me bad advice. ¯\_(ツ)_/¯

Final final note: if you try a plain podman run curl ... without first pulling the image, it won't know which image you actually want, and none of the three prompts it gives you (registry.fedoraproject.org, registry.access.redhat.com, docker.io/library) are the official upstream image. I've submitted a PR to the containers/shortnames repo to fix that, so a plain curl image name will automatically be aliased to the upstream image.