$ pip install netshape

Simulate any network.No admin, no OS rules,no friction.

See how your app behaves on 2G, satellite, congested networks — all from a single command. Cross-platform. Open source.

$pip install netshape

terminal — zsh

What is NetShape?

A local throttling proxy for testing any process under degraded network conditions — no OS-level rules, no admin required.

You type netshape run --profile 3g -- your-app and NetShape launches your app inside a simulated network environment. Every HTTP request, every WebSocket connection, every API call — all go through the throttling proxy.

Open another terminal and run netshape adjust --latency 500ms — changes take effect instantly. No restart, no rebuild, no waiting.

When your app exits or you press Ctrl-C, the proxy dies. Your network reverts immediately. Nothing lingers. No cleanup needed.

◈

NetShape Proxy

127.0.0.1:8090

→Token Bucket (bandwidth)

⏱Delay (latency + jitter)

✕Random drop (packet loss)

App

⇄

Internet

Why proxy over OS-level rules?

Proxy-based approach

NetShape runs a local HTTP forward proxy that your app routes traffic through. No MITM, no certificate installation — HTTPS is tunneled transparently via CONNECT.

Process death = auto-revert

When the proxy process exits, your network reverts instantly. No lingering OS rules, no cleanup commands, no safety concerns. Crash-safe by design.

Zero admin privileges

Everything runs in userspace. No sudo, no administrator prompts, no security policy exceptions. Works on locked-down corporate machines without IT approval.

Cross-platform from day one

Identical experience on macOS, Windows, and Linux. No platform-specific backends, no native binaries, no compatibility matrix. One Python package everywhere.

Features

Everything you need to test app behavior under real-world network conditions.

12 Built-in Profiles

From 2G (50 Kbps, 500ms latency) to fiber (1 Gbps, 5ms). Mobile, broadband, satellite, offline — every real-world condition covered.

Live Adjustment

Change bandwidth, latency, loss, and jitter on a running proxy session. No restart needed — changes apply instantly.

Web Dashboard

Real-time throughput and latency charts, sliders for every parameter, live log viewer, and scenario runner — all from your browser at localhost:8091.

Per-Endpoint Rules

Throttle specific domains differently. Regex-based pattern matching — throttle your payment API at 1 Mbps while the rest runs at full speed.

Scenario Scripting

Simulate dynamic network transitions over time with YAML scenarios. Subway commute, flight mode, coffee shop Wi-Fi — built-in or custom.

Metrics Export

Prometheus text format export, JSON log files with rotation, rich terminal tables with live refresh, and 12 tracked metric counters.

Full Protocol Support

HTTP/1.x, HTTPS via CONNECT tunnel, HTTP/2 over TLS, WebSocket — all throttled transparently through a single local proxy.

Zero Dependencies

No admin required. No OS-level rules. No native binaries. One pip install, cross-platform. Process death = automatic cleanup. Nothing lingers.

Quick Start

Get throttling in 30 seconds. No sign-up, no config files, no admin prompts.

Install

bash

pip install netshape

Run your app through the proxy

bash

# Start a session with 3G throttling
netshape run --profile 3g -- your-app

# Or with custom settings
netshape run --bandwidth 500kbps --latency 300ms -- your-app

Adjust live in another terminal

bash

# Change bandwidth on the fly
netshape adjust --bandwidth 10mbps

# Switch to a different profile
netshape adjust --profile satellite

# Check status
netshape status

# Stop when done
netshape stop

Installation

One command. Zero dependencies beyond Python. Cross-platform.

bash

pip install netshape

Dev install (editable)

bash

git clone https://github.com/aarush-dhingra/netshape
cd netshape
pip install -e ".[dev,scenarios]"

Verify installation

bash

netshape --version
# netshape 1.0.1

Requirements

Python ≥ 3.10
pip (comes with Python)
No admin/sudo needed
No native binaries
No platform-specific backends

Dev install extras

netshape[dev]

pytest, pytest-asyncio, bandit, pip-audit — for contributing.