{"id":19661342,"url":"https://github.com/lbryio/aioupnp","last_synced_at":"2025-12-13T20:08:38.666Z","repository":{"id":55565427,"uuid":"142632512","full_name":"lbryio/aioupnp","owner":"lbryio","description":"UPnP for asyncio","archived":false,"fork":false,"pushed_at":"2023-06-21T01:53:37.000Z","size":426,"stargazers_count":29,"open_issues_count":8,"forks_count":7,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-15T09:07:43.198Z","etag":null,"topics":["asyncio","dd-wrt","miniupnpc","python","python3","scpd","ssdp","upnp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lbryio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-07-27T23:48:58.000Z","updated_at":"2024-02-27T14:06:40.000Z","dependencies_parsed_at":"2022-08-15T03:20:18.875Z","dependency_job_id":"de5d63f8-0a8b-4cdc-ab13-56236b7ac88e","html_url":"https://github.com/lbryio/aioupnp","commit_stats":{"total_commits":249,"total_committers":6,"mean_commits":41.5,"dds":0.03614457831325302,"last_synced_commit":"e6d5c86efbe7f06c83f3b71886812ac9b6b4e71a"},"previous_names":["lbryio/txupnp"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbryio%2Faioupnp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbryio%2Faioupnp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbryio%2Faioupnp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbryio%2Faioupnp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lbryio","download_url":"https://codeload.github.com/lbryio/aioupnp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251384007,"owners_count":21580988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","dd-wrt","miniupnpc","python","python3","scpd","ssdp","upnp"],"created_at":"2024-11-11T16:06:59.396Z","updated_at":"2025-12-13T20:08:33.272Z","avatar_url":"https://github.com/lbryio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://github.com/lbryio/aioupnp/workflows/CI/badge.svg)\n[![codecov](https://codecov.io/gh/lbryio/aioupnp/branch/master/graph/badge.svg)](https://codecov.io/gh/lbryio/aioupnp)\n[![PyPI version](https://badge.fury.io/py/aioupnp.svg)](https://badge.fury.io/py/aioupnp)\n[![Python 3.6](https://img.shields.io/badge/python-3.6-blue.svg)](https://www.python.org/downloads/release/python-360/)\n[![Python 3.7](https://img.shields.io/badge/python-3.7-blue.svg)](https://www.python.org/downloads/release/python-370/)\n[![Python 3.8](https://img.shields.io/badge/python-3.8-blue.svg)](https://www.python.org/downloads/release/python-380/)\n\n# UPnP for asyncio\n\n`aioupnp` is a python 3.6-8 library and command line tool to interact with UPnP gateways using asyncio. `aioupnp` requires the `netifaces` and `defusedxml` modules.\n\n## Supported devices\n![img](https://i.imgur.com/JtO4glP.png)\n\n## Installation\n\nVerify python is version 3.6-8\n```\npython --version\n```\n\n#### Installation for normal usage\n```\npip install aioupnp\n```\n\n#### Installation for development\n```\ngit clone https://github.com/lbryio/aioupnp.git\ncd aioupnp\npip install -e .\n```\n\n\n## Usage\n\n```\naioupnp [-h] [--debug_logging] [--interface=\u003cinterface\u003e] [--gateway_address=\u003cgateway_address\u003e]\n        [--lan_address=\u003clan_address\u003e] [--timeout=\u003ctimeout\u003e]\n        [(--\u003ccase sensitive m-search header\u003e=\u003cvalue\u003e)...]\n        command [--\u003carg name\u003e=\u003carg\u003e]...\n```\n\n\n#### Commands\n* `help`\n* `get_external_ip`\n* `m_search`\n* `add_port_mapping`\n* `get_port_mapping_by_index`\n* `get_redirects`\n* `get_specific_port_mapping`\n* `delete_port_mapping`\n* `get_next_mapping`\n* `gather_debug_info`\n\n#### To get the documentation for a command\n\n    aioupnp help get_external_ip\n\n#### To get the external ip address\n\n    aioupnp get_external_ip\n\n#### To list the active port mappings on the gateway\n\n    aioupnp get_redirects\n\n#### To set up a TCP port mapping\n    \n    aioupnp add_port_mapping --external_port=1234 --internal_port=1234 --lan_address=\u003clan_addr\u003e --description=test --protocol=TCP\n\n#### To delete a TCP port mapping\n\n    aioupnp delete_port_mapping --external_port=1234 --protocol=TCP\n\n#### M-Search headers\nUPnP uses a multicast protocol (SSDP) to locate the gateway. Gateway discovery is automatic by default, but you may provide specific headers for the search to use to override automatic discovery.\n\nIf m-search headers are provided as keyword arguments then all of the headers to be used must be provided, in the order they are to be used. For example:\n\n    aioupnp --HOST=239.255.255.250:1900 --MAN=\\\"ssdp:discover\\\" --MX=1 --ST=upnp:rootdevice m_search\n\n#### Using non-default network interfaces\nBy default, the network device will be automatically discovered. The interface may instead be specified with the `--interface`, provided before the command to be run. The gateway used on the interface network may be specified with the `--gateway_address` argument.\n\n    aioupnp --interface=wlp4s0 --gateway_address=192.168.1.6 m_search\n\n\n#### Example usage from python\n\n    from aioupnp.upnp import UPnP\n\n    async def main():\n        upnp = await UPnP.discover()\n        print(await upnp.get_external_ip())\n        print(await upnp.get_redirects())\n\n        print(\"adding a port mapping\")\n        await upnp.add_port_mapping(1234, 'TCP', 1234, upnp.lan_address, 'test mapping')\n        print(await upnp.get_redirects())\n\n        print(\"deleting the port mapping\")\n        await upnp.delete_port_mapping(1234, 'TCP')\n        print(await upnp.get_redirects())\n\n\n    asyncio.run(main())\n\n\n## Troubleshooting\nIf `aioupnp` is failing with m-search timeouts this means the UPnP gateway (the router) isn't being found at all. To see if this error is expected try running m_search with debug logging, which will print out the packets sent and received:\n\n    aioupnp --debug_logging m_search\n\nIf you only see packets being sent or the replies are only from devices that aren't your router (smart devices, speakers, etc), then there are three options:\n* your router does not support UPnP (this is unlikely)\n* UPnP is turned off in the web gui for your router (more likely)\n* `aioupnp` has a bug (very likely if you don't see your router manufacturer doing well in the supported devices table)\n\nIf you see replies from the router but it still fails, then it's likely a bug in aioupnp.\n\nIf there are no replies and UPnP is certainly turned on, then a local firewall is the likely culprit.\n\n\n## Sending a bug report\n\nIf it still doesn't work, you can send a bug report using an included script. This script will try finding the UPnP gateway using `aioupnp` as well as `miniupnpc` and then try add and remove a port mapping using each library. The script does this while capturing the packets sent/received, which makes figuring out what went wrong possible. The script will create a file with this packet capture (`aioupnp-bug-report.json`) and automatically send it.\n\nNote: the bug report script currently does not work on MacOS\n```\ngit clone https://github.com/lbryio/aioupnp.git\ncd aioupnp\npython3 -m pip install -e .\n\npython3 -m pip install --user certifi aiohttp miniupnpc\nsudo -E python3 generate_bug_report.py\n```\n\n## License\n\nThis project is MIT licensed. For the full license, see [LICENSE](LICENSE).\n\n## Contact\n\nThe primary contact for this project is [@jackrobison](mailto:jackrobison@lbry.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flbryio%2Faioupnp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flbryio%2Faioupnp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flbryio%2Faioupnp/lists"}