---
id: portforward
version: "0.7.6"
license: MIT License
license_treatment: permissive
maintenance: active
---

# portforward — Easy Kubernetes Port-Forward For Python

License: permissive · Maintenance: active · Downloads: 275.5K/mo

## What it is and what it does

portforward is a Python library that wraps Kubernetes port-forwarding functionality, letting you programmatically tunnel local ports to pods or services in a cluster without invoking kubectl as a subprocess. It reads your kubeconfig (or a path you provide) and establishes the same kind of port-forward connection that kubectl port-forward would create, but from within Python code.

The library is built on Rust via PyO3 for performance and reliability. It supports both synchronous context-manager usage and async clients, can forward to either pods or services (trying pods first), and handles multiple forwards per target. It's useful for integration testing, local development against staging clusters, or any scenario where you need programmatic access to remote services without manual kubectl commands.

Use it for:

- Integration tests that need to reach Kubernetes services from a test runner without spawning kubectl subprocesses.
- Local development workflows where you want to proxy a remote service to localhost within a Python application.
- Automated deployment or health-check scripts that need to temporarily access cluster services.
- Multi-service testing setups where you forward several pods to different local ports in a single test session.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides Python bindings for Kubernetes port-forwarding, allowing you to forward local ports to pods or services in a cluster using your kubeconfig file.

Yes, if you need programmatic Kubernetes port-forwarding in Python. The package is actively maintained, has no known vulnerabilities, supports modern Python versions with pre-built wheels, and solves a real problem for developers and CI/CD pipelines. The MIT license is permissive. Install friction is moderate due to Rust compilation, but wheels cover most platforms. Start with the quickstart example in the documentation.

## Install

pip install portforward
uv add portforward
poetry add portforward

## Installing portforward

Before you install: Medium install friction due to compiled Rust components, but wheels are available for Python 3.9–3.13 across Windows, macOS, and Linux (including Alpine). Installation from source requires Rust toolchain. Last release was 197 days ago; repository is active with recent commits.

License in practice: MIT License permits commercial and private use with minimal restrictions; you may use, modify, and distribute this package freely as long as you include the license notice.

Quickstart:

pip install portforward

import portforward

with portforward.forward("default", "my-pod", 9000, 80):
    # Local port 9000 now forwards to port 80 on the pod
    pass

Requires a valid kubeconfig file (defaults to ~/.kube/config) and access to a Kubernetes cluster; Rust is needed only if installing from source on an unsupported platform.

Verify before relying:

- Whether the package supports async/await patterns beyond the context manager interface mentioned in the description.
- Performance characteristics and limits on concurrent port forwards or sustained traffic throughput.
- Compatibility with non-standard kubeconfig formats or authentication methods beyond standard kubectl setup.

## Package facts

- License: MIT License (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 275.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

kubernetes port forward python, k8s port forwarding library, kubectl port-forward programmatic, local port to pod tunnel, kubernetes service proxy python, kubernetes, port-forwarding, devops

[View on SkillFed](https://skillfed.io/packages/portforward) · [View on PyPI](https://pypi.org/project/portforward/)