Install & Compatibility
Where this runs
tested against v3.0.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.8s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TunTapDevice
✓ from pytun_pmd3 import TunTapDevice
✗ from pytun import TunTapDevice
This quickstart demonstrates how to create an IPv6-only TUN device, bring it up, and configure its IPv6 address. It then enters a brief loop to show packet reception. Remember to run with appropriate permissions.
import os
import sys
import time
from pytun import TunTapDevice, IFF_TUN, IFF_NO_PI
# Note: Requires appropriate permissions (e.g., run as root/administrator
# or user added to 'tun' group on Linux). On Windows, the wintun driver
# might need manual installation first, though pytun-pmd3 attempts to manage it.
try:
# Use a unique name to avoid conflicts, or a fixed one for specific setup
device_name = os.environ.get('PYTUN_DEV_NAME', 'pytun-pmd3-tun0')
tun = TunTapDevice(name=device_name, flags=IFF_TUN | IFF_NO_PI)
print(f"Created TUN device: {tun.name}")
tun.up()
print(f"Device {tun.name} is up.")
# Configure IPv6 address (pytun-pmd3 is IPv6-ONLY)
ipv6_address = os.environ.get('PYTUN_IPV6', 'fcd0::1/64')
tun.ifconfig(ipv6=ipv6_address)
print(f"Configured IPv6 address {ipv6_address} on {tun.name}")
print(f"\nDevice {tun.name} configured. You can now try pinging its address.")
print("Example: ping fcd0::1 (from another host/interface that can route to it)")
print("Waiting for 10 seconds. Press Ctrl+C to stop.")
start_time = time.time()
while time.time() - start_time < 10:
try:
# Read up to 1500 bytes with a 1-second timeout
packet = tun.read(1500, timeout=1)
if packet:
print(f"Received {len(packet)} bytes from TUN device.")
sys.stdout.flush()
except Exception as e:
# Ignore common 'Resource temporarily unavailable' when no packets
pass
time.sleep(0.1)
except PermissionError:
print("Error: Permission denied. Try running as root/administrator or")
print("ensure your user has appropriate permissions (e.g., added to 'tun' group).")
print("On Linux: sudo usermod -a -G tun $(whoami) && sudo reboot")
except FileNotFoundError as e:
print(f"Error: File not found: {e}")
print("On Windows, ensure the wintun driver is correctly installed and accessible.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
finally:
if 'tun' in locals():
try:
print(f"Closing TUN device: {tun.name}")
tun.close()
print("Device closed.")
except Exception as e:
print(f"Error closing TUN device: {e}")
Debug
Known issues
breakingpytun-pmd3 is strictly IPv6-ONLY. If you are migrating from the original `pytun` library, any existing IPv4 configurations or attempts to send/receive IPv4 packets will not work.fixEnsure your application and network configuration are designed for IPv6 exclusively when using pytun-pmd3. For IPv4 support, use the original `pytun` library.
affects: All versions
gotchaCreating and configuring TUN/TAP devices typically requires elevated permissions (root/administrator). Running your Python script without these permissions will result in `PermissionError`.fixOn Linux, run with `sudo` or add your user to the `tun` group (`sudo usermod -a -G tun $(whoami) && sudo reboot`). On Windows, run your terminal/IDE as administrator.
affects: All versions
gotchaOn Windows, pytun-pmd3 relies on the Wintun driver. While the library attempts to manage this, you might occasionally need to manually ensure the Wintun driver is installed and accessible for device creation.fixIf encountering `FileNotFoundError` or similar issues on Windows, verify that the Wintun driver is correctly installed. Refer to the Wintun project for manual installation instructions if necessary.
affects: All versions on Windows
deprecatedPrior to v3.0.0, the internal implementation relied on C extensions. Version 3.0.0 refactored the library to use pure Python with `ctypes`. While the public API is largely consistent, if you were relying on any internal C-level details, this change could affect you.fixUpgrade to v3.x.x and ensure your code only interacts with the documented public API (e.g., `TunTapDevice`, `up`, `ifconfig`, `read`, `write`, `close`).
affects: <3.0.0
Upgrade
Version history
3.0.3latest on PyPI · released Jan 27, 2026
Audit
Dependencies
No dependency data recorded yet.