Welcome to portforward’s documentation!

::

This library is in maintenance mode. I will review and merge small pull requests when needed, e.g for bugfixes. I won’t transfer ownership to keep trust in this library and to protect the users of this library against supply chain attacks. But I am willing place references here to a new library when someone has an awesome idea for new enhanced version. You may ask why. The burden is to big for me to keep up with two ecosystem in my spare time.

portforward

https://img.shields.io/pypi/v/portforward.svg https://img.shields.io/pypi/status/portforward.svg PyPI - Downloads Documentation Status Build status

Easy Kubernetes Port-Forward For Python

Installation

Wheels are available for:

  • Windows (architectures: x64, x86)

  • macOS (architectures: x86_64, aarch64)

  • Linux (architectures: x86_64, x86, aarch64, armv7, s390x, ppc64le)

Musllinux wheels (Alpine‑compatible) are provided for x86_64, x86, aarch64 and armv7.

with Python versions:

  • 3.9

  • 3.10

  • 3.11

  • 3.12

  • 3.13

Requirements for installation from source

The following things are required when there is no wheel available for the target system.

Pip knows how to install portforward.

pip install portforward

Quickstart

import requests

import portforward


def main():
    namespace = "test"
    pod_name = "web"  # You can also use a service name instead
    local_port = 9000  # from port
    pod_port = 80  # to port

    # No path to kube config provided - will use default from $HOME/.kube/config
    with portforward.forward(namespace, pod_name, local_port, pod_port):
        response = requests.get("http://localhost:9000")
        print(f"Done: \n'{response.status_code}'\n'{response.text[:20]}...'")


if __name__ == "__main__":
    main()

Features

  • Native Kubernetes port-forwarding with the .kube/config from the home dir or any other path to config.

  • Portforward for pods and services - the lib will first look for a pod with matching name then for a service

  • Waiting for a pod to become ready

  • Multiple forwards per pod or service

  • As context manager, sync or async client

Development

In case you want to develop on this library itself please take a look at the CONTRIBUTING page.

Credits

This project is enabled by PyO3.

Indices and tables