docker-port-forward

A Docker CLI plugin that mirrors the kubectl port-forward interface. Forward one or more local ports to a running container or a Docker Compose service, without publishing ports or modifying the container.

Installation

Install as a Docker CLI plugin with a single command:

curl -fsSL https://raw.githubusercontent.com/dokku/docker-port-forward/main/install.sh | sh

Or build from source:

make install

Or download a pre-built binary from GitHub Releases and place it in ~/.docker/cli-plugins/ as docker-pf. See the Getting Started guide for details.

Once installed, the plugin is available via docker pf.

Usage

Forward localhost:8080 to port 80 on a running container:

docker pf my-container 8080:80

Auto-allocate a local port:

docker pf my-container :5000

Forward to a Compose service by name (with an auto-detected compose file):

docker pf service/web 8080:80

Forward multiple ports at once:

docker pf my-container 8080:80 5432:5432

Auto-detect all non-loopback TCP and UDP listeners in a container and forward each on its own port:

docker pf my-container

Forward UDP (DNS-style):

docker pf my-dns 5353:53/udp

Mix TCP and UDP in one invocation:

docker pf my-app 8080:80 53:53/udp

Run in the background and give the helper an explicit name:

docker pf --detach --name mydb my-db 5432:5432

Remove any leftover helper containers from crashed or detached sessions:

docker pf cleanup
docker pf cleanup --name mydb

See the command reference for all flags and options.

Documentation

• Getting Started -- why docker-port-forward, installation, and your first forward
• Command Reference -- all CLI flags and arguments
• Target Resolution -- how container/, service/, and bare-name targets are resolved
• Compose Integration -- resolving Compose services with -f/-p/profiles
• Helper Image -- what the sidecar does, why, and how to override --helper-image
• Limitations -- network modes, target configurations, and host setups that are not supported

License

MIT