#3388·docker-py

Does `ContainerCollection.run`'s `ports` field support the `(address, None)` tuple for the host port mapping?

Author: slavistanCreated Mar 3, 2026Updated Mar 3, 2026

The documentation of the ports field for the ContainerCollection's run method allows, among others, the following value shapes:

- `None`, to assign a random host port. For example,
  `{'2222/tcp': None}`.
- A tuple of `(address, port)` if you want to specify the host interface. For example,
  `{'1111/tcp': ('127.0.0.1', 1111)}`.

My question is whether a tuple of (address, None) is also supported in order to specify the host interface AND request that the daemon pick a free host port. E.g. is {'1111/tcp': ('127.0.0.1', None)} officially supported?

I've tinkered around with this setting and it seems to work (on my machine™). May I kindly ask you to confirm this? If it works and this is just a matter of incomplete documentation, I'll create a PR for the docs.

Thanks.