Sometimes you want to cap how much bandwidth a server uses. Maybe a backup job is saturating your uplink during business hours, maybe you want to simulate a slow connection to test your app, or maybe you're sharing a server between processes and one of them is eating everything. Wondershaper is the simplest tool to handle this.
It's a thin wrapper around Linux's built-in tc (Traffic Control) command, which uses HTB (Hierarchical Token Bucket) queueing under the hood. You could write the same rules directly with tc, but the syntax is painful. Wondershaper turns it into a one-liner.
Bandwidth shaping is one of those tools you don't think about until you really need it. Common scenarios:
Backup jobs that saturate your uplink. Rsync, restic, or borgbackup can easily push 1 Gbps if your storage allows. If your server is also serving traffic, the backup will starve everything else. Limit the backup to a fraction of your bandwidth and the rest of your services stay responsive.
Shared servers between teams or projects. If multiple processes share a server, capping each one's bandwidth prevents one from monopolizing the link.
Testing under bad network conditions. Simulating a slow connection is the only way to find out how your app behaves for users on weak mobile networks. Wondershaper makes that easy without touching client-side tooling.
Avoiding cloud overage charges. If your provider charges per GB over a monthly cap, throttling bandwidth caps your monthly cost too.
eth0, ens3, enp0s3, or similar)Find your interface name with:
ip -br link showYou'll see something like:
lo UNKNOWN 00:00:00:00:00:00
eth0 UP aa:bb:cc:dd:ee:ffUse the name that shows UP and isn't lo. The examples below assume eth0. Adapt to whatever your interface is called.
On Debian and Ubuntu:
sudo apt update
sudo apt install wondershaper -yOn older Ubuntu releases, the apt package works fine. On Ubuntu 22.04 and 24.04, some users report the apt version has issues with newer kernels. If you run into problems (see troubleshooting at the end), install from the official GitHub repository instead:
sudo apt install git -y
git clone https://github.com/magnific0/wondershaper.git
cd wondershaper
sudo make installThis version is actively maintained and matches what modern kernels expect.
The basic syntax is:
sudo wondershaper <interface> <download_kbps> <upload_kbps>To limit eth0 to 300 Mbps download and 200 Mbps upload:
sudo wondershaper eth0 300000 200000The values are in kilobits per second. So 300000 = 300 Mbps. A few common conversions:
If you only want to limit one direction, pass 0 for the other:
# Limit only download to 100 Mbps
sudo wondershaper eth0 100000 0
# Limit only upload to 50 Mbps
sudo wondershaper eth0 0 50000Check the current shaping rules:
sudo wondershaper eth0You should see the configured limits. You can also inspect the underlying tc rules directly:
tc qdisc show dev eth0
tc class show dev eth0Run a quick speed test to confirm. From the server:
curl -o /dev/null https://speed.cloudflare.com/__down?bytes=100000000The transfer speed reported should match your configured download limit.
When you're done, clear all shaping rules:
sudo wondershaper clear eth0The interface goes back to full speed immediately. No reboot needed.
Wondershaper doesn't survive a reboot by default. The shaping rules live in kernel memory and get wiped when the system restarts.
To make limits persistent, create a systemd service:
sudo nano /etc/systemd/system/wondershaper.servicePaste:
[Unit]
Description=Bandwidth shaping with Wondershaper
After=network.target
[Service]
Type=oneshot
ExecStart=/usr/sbin/wondershaper eth0 300000 200000
ExecStop=/usr/sbin/wondershaper clear eth0
RemainAfterExit=yes
[Install]
WantedBy=multi-user.targetAdjust the interface name and limits to match your setup. Then enable and start:
sudo systemctl daemon-reload
sudo systemctl enable wondershaper
sudo systemctl start wondershaperNow your limits apply automatically on every boot.
"Cannot find device 'eth0'". Your interface isn't called eth0. Run ip -br link show and use the actual name.
Wondershaper command not found. The apt package didn't install correctly, or /usr/sbin isn't in your $PATH. Try the full path: sudo /usr/sbin/wondershaper eth0 300000 200000. If that fails, install from GitHub as described in Step 1.
Limits don't take effect. Some virtualized environments restrict kernel-level traffic shaping. Check with tc qdisc show dev eth0. If you see only noqueue, your kernel may not have the sch_htb module loaded. Try sudo modprobe sch_htb and rerun the command.
Performance is worse than the limit you set. HTB shaping has some overhead, especially at very high speeds. Setting a limit close to your line speed (say 950 Mbps on a 1 Gbps link) may actually deliver slightly less than 950 Mbps because of the shaping overhead. Leave a margin of 5 to 10% if precise throughput matters.
Multiple processes share the limit. Wondershaper limits the entire interface, not per-process. If you need per-process limits, look at trickle or use tc with classful queueing rules.
IPv6 traffic is also shaped, but separately. Wondershaper applies to all traffic on the interface. If you only want to shape IPv4 or IPv6 specifically, you'll need to write tc rules directly.
Bandwidth shaping (what Wondershaper does) limits speed in real time. It doesn't reduce your monthly transfer total directly, but slower speeds mean you transfer less data per hour.
If your goal is to stay under a monthly transfer quota imposed by your provider, shaping is a workaround but not a solution. The provider is still measuring bytes transferred, not your peak speed. We covered this in detail in Why Bandwidth Caps Matter More Than You Think.
Wondershaper is the right tool when you want to control how a single server uses its connection, not when you want to dodge billing caps.
Take control of your dedicated server (settings, data ...) without any limits in apps usage.
What are you waiting for ?
We are waiting you on community zone. More than 70 guides (sysadmin, gaming, devops...) !
Let me check
