{"id":7639,"library":"pytun-pmd3","title":"PyTun-PMD3 (IPv6-ONLY TUN device)","description":"pytun-pmd3 is a fork of the original python-pytun library, providing support for TUN/TAP network devices on Darwin (macOS), Windows, and Linux. It exclusively supports IPv6, making it suitable for applications like VPNs that specifically require IPv6 tunneling. The library is currently at version 3.0.3 and has a moderate release cadence, focusing on bug fixes and platform compatibility.","status":"active","version":"3.0.3","language":"en","source_language":"en","source_url":"https://github.com/doronz88/pytun-pmd3","tags":["network","tun","tap","vpn","ipv6","windows","linux","macos"],"install":[{"cmd":"pip install pytun-pmd3","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"TunTapDevice","correct":"from pytun import TunTapDevice"},{"symbol":"IFF_TUN","correct":"from pytun import IFF_TUN"},{"symbol":"IFF_NO_PI","correct":"from pytun import IFF_NO_PI"}],"quickstart":{"code":"import os\nimport sys\nimport time\nfrom pytun import TunTapDevice, IFF_TUN, IFF_NO_PI\n\n# Note: Requires appropriate permissions (e.g., run as root/administrator\n# or user added to 'tun' group on Linux). On Windows, the wintun driver\n# might need manual installation first, though pytun-pmd3 attempts to manage it.\n\ntry:\n    # Use a unique name to avoid conflicts, or a fixed one for specific setup\n    device_name = os.environ.get('PYTUN_DEV_NAME', 'pytun-pmd3-tun0')\n    tun = TunTapDevice(name=device_name, flags=IFF_TUN | IFF_NO_PI)\n    print(f\"Created TUN device: {tun.name}\")\n\n    tun.up()\n    print(f\"Device {tun.name} is up.\")\n\n    # Configure IPv6 address (pytun-pmd3 is IPv6-ONLY)\n    ipv6_address = os.environ.get('PYTUN_IPV6', 'fcd0::1/64')\n    tun.ifconfig(ipv6=ipv6_address)\n    print(f\"Configured IPv6 address {ipv6_address} on {tun.name}\")\n\n    print(f\"\\nDevice {tun.name} configured. You can now try pinging its address.\")\n    print(\"Example: ping fcd0::1 (from another host/interface that can route to it)\")\n    print(\"Waiting for 10 seconds. Press Ctrl+C to stop.\")\n\n    start_time = time.time()\n    while time.time() - start_time < 10:\n        try:\n            # Read up to 1500 bytes with a 1-second timeout\n            packet = tun.read(1500, timeout=1)\n            if packet:\n                print(f\"Received {len(packet)} bytes from TUN device.\")\n            sys.stdout.flush()\n        except Exception as e:\n            # Ignore common 'Resource temporarily unavailable' when no packets\n            pass\n        time.sleep(0.1)\n\nexcept PermissionError:\n    print(\"Error: Permission denied. Try running as root/administrator or\")\n    print(\"ensure your user has appropriate permissions (e.g., added to 'tun' group).\")\n    print(\"On Linux: sudo usermod -a -G tun $(whoami) && sudo reboot\")\nexcept FileNotFoundError as e:\n    print(f\"Error: File not found: {e}\")\n    print(\"On Windows, ensure the wintun driver is correctly installed and accessible.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if 'tun' in locals():\n        try:\n            print(f\"Closing TUN device: {tun.name}\")\n            tun.close()\n            print(\"Device closed.\")\n        except Exception as e:\n            print(f\"Error closing TUN device: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your application and network configuration are designed for IPv6 exclusively when using pytun-pmd3. For IPv4 support, use the original `pytun` library.","message":"pytun-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.","severity":"breaking","affected_versions":"All versions"},{"fix":"On 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.","message":"Creating and configuring TUN/TAP devices typically requires elevated permissions (root/administrator). Running your Python script without these permissions will result in `PermissionError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If 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.","message":"On 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.","severity":"gotcha","affected_versions":"All versions on Windows"},{"fix":"Upgrade to v3.x.x and ensure your code only interacts with the documented public API (e.g., `TunTapDevice`, `up`, `ifconfig`, `read`, `write`, `close`).","message":"Prior 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.","severity":"deprecated","affected_versions":"<3.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `pip uninstall pytun` if you only intend to use `pytun-pmd3`. Then `pip install pytun-pmd3`. The import `from pytun import TunTapDevice` will then correctly resolve to the `pytun-pmd3` version.","cause":"You likely have the original `pytun` library installed, or pytun-pmd3 is not correctly installed/accessible, leading to the wrong `pytun` module being imported.","error":"AttributeError: module 'pytun' has no attribute 'TunTapDevice'"},{"fix":"Run your Python script with elevated privileges (e.g., `sudo python your_script.py` on Linux/macOS, or 'Run as administrator' on Windows). On Linux, you can also add your user to the 'tun' group: `sudo usermod -a -G tun $(whoami) && sudo reboot`.","cause":"Operating system permission restrictions prevent the creation or configuration of the TUN/TAP device.","error":"PermissionError: [Errno 13] Permission denied"},{"fix":"Verify that the Wintun driver is correctly installed on your system. Sometimes, a system reboot after installation is required. Ensure the driver files are where `pytun-pmd3` expects them.","cause":"On Windows, the Wintun driver might not be installed or accessible, preventing the TUN device from being created.","error":"OSError: [Errno 19] No such device (Windows) or similar driver-related errors."},{"fix":"Use IPv6 addresses for all configurations (`tun.ifconfig(ipv6='...')`) and ensure your application sends and expects IPv6 packets through the device. If IPv4 support is required, you must use the original `pytun` library, not `pytun-pmd3`.","cause":"pytun-pmd3 is explicitly designed for IPv6-ONLY operation. It does not support IPv4.","error":"IPv4 traffic is not flowing through the TUN device, or `tun.ifconfig(ipv4='...')` fails."}]}