A NAT-PMP client library for Python

Something that I’ve put together and might be somewhat useful to others. I wrote a NAT-PMP (Network Address Translation Port Mapping Protocol) library and testing client in Python. The client allows you to set up dynamic port mappings on NAT-PMP compatible routers. Thus this is a means for dynamic NAT traversal with routers that talk NAT-PMP. In practical terms, this is basically limited to the newer Apple AirPort base stations and the AirPort Express, which have support for this protocol. I’m currently unable to support UPnP (the dominant port mapping protocol in non-Apple routers), though I’m sure either someone has written bindings for Python, or I’ll have to do it eventually once my AirPort Express dies.

In any case, this library puts a thin layer of Python abstraction over the NAT-PMP protocol, version 0, as specified by the NAT-PMP draft standard.  The purpose of this is simple.  I needed to establish port forwarding without rebooting my AirPort router.

Normally, when you need to have a public port on your router forwarded to a private port on your box behind it (say, if you write a server that listens on a port, or have a P2P client running on a port) you’d have to fire up AirPort Utility.app -> Advanced -> Port Mappings, set your mappings, and then hit Update…which reboots the router, killing your network connection and anything you might be doing. There has been no good way to do this programmatically with AirPort routers, when your program needs to negotiate a port forwarding with no manual intervention. Further, there isn’t a command-line tool to open up a port when you’re SSH’ed into your machine but don’t have a GUI.

Creating the port mappings dynamically via NAT-PMP allows port forwarding to happen without the reboot. When my server runs, it can make a call to the router to start forwarding a port.  Furthermore, when I’m done with testing my server, I stop renewing the port mapping, and it expires when its lifetime runs out.  Thus, I won’t forget to delete the mapping later (and reboot the router yet again) when I want that port secured behind the NAT.


py-natpmp repository on Github. If you want the unpackaged source code, you can find the latest versions there.

py-natpmp-0.2.1.tar.gz – a proper Python setuptools package for py-natpmp, if you’re rather take a tarball.

(To enable NAT-PMP on the AirPort router, go to AirPort Utility.app -> Internet -> NAT -> Enable NAT Port Mapping Protocol. Requires Mac OS X 10.4 to succeed. Older AirPort utility software may have this option hidden elsewhere.)

The code is BSD licensed, so feel free to take it. I’d love knowing where this code ends up (just out of personal curiosity), if you drop me a line, but that’s quite optional.


To use the client, grab it and the above library. Make sure you have the library in the same directory as the client script or otherwise on your Python instance’s sys.path. Invoke the client on the command-line (Terminal.app) as python natpmp-client.py [-u] [-l lifetime] [-g gateway_addr] public_port private_port.

For example:

python natpmp-client.py -u -l 1800 60009 60009
Create a mapping for the public UDP port 60009 to the private UDP port 60009 for 1,800 seconds (30 minutes)
python natpmp-client.py 60010 60010
Create a mapping for the public TCP port 60010 to the private TCP port 60010
python natpmp-client.py -g 60011 60022
Explicitly instruct the gateway router to create the TCP mapping from 60010 to 60022

Remember to turn off your firewall for those ports that you map.


The library provides a set of high-level and low-level functions to interact via the NAT-PMP protocol. The functions map_port and get_public_address provide the two high-level functions offered by NAT-PMP. Responses are stored as Python objects.

The code is fairly well-documented, so consult the NATPMP.py file for usage details.


This is an incomplete implementation of the specification.  When the router reboots, all dynamic mappings are lost.  The specification provides for notification packets to be sent by the router to each client when this happens.  There is no support in this library and client to monitor for such notifications, nor does it implement a daemon process to do so.  The specification recommends queuing requests – that is, all NAT-PMP interactions should happen serially.  This simple library does not queue requests – if you abuse it with multithreading, it will send those requests in parallel and possibly overwhelm the router.

The library will attempt to auto-detect your NAT gateway. This is done via a popen to netstat on BSDs/Darwin and ip on Linux. This is likely to fail miserably, depending on how standard the output is. In the library, a keyword argument is provided to override the default and specify your own gateway address. In the client, use the -g switch to manually specify your gateway.


This is a relatively simple library that I am using in aiding my development work, and provides for port forwarding and NAT traversal in my personal Python apps.  It may also come in handy for you in your Python code — if nothing else, as a reference to see how to interact with the router via the protocol. It is not elegant/well tested, and not meant for daily use by a normal user.  If you use the library in your code and it does not work for your configuration, I would be happy to take bug reports (or even better, patches!).

The client is intended for demonstration purposes only, though I personally use it as a command-line sysadmin tool for when I’m away from my machine but need to open up a port.

If you are a typical user looking for port forwarding tools, this is not for you. For an actual, well-designed, user-friendly program to perform dynamic port mappings on the Mac, try the great shareware package Lighthouse, which provides a user-friendly menu bar extra, persistent port mapping profiles, and UPnP support for your non-Apple routers.

Updated Feb 10, 2010
– Repackaged with setuptools. Fixed major bugs on systems that fail to detect the gateway automatically. Experimental Windows 7 support.
Updated Feb 05, 2008
– Removed broken mutexes, pending work to implement a decent request queue. Allow me to reiterate that this library is currently non-compliant with the specification’s recommendation to queue NAT-PMP requests. Try not to abuse your router when using this library in multithreaded Python code.
– Added some gateway autodetection on NT systems via netstat. Thanks to roee shlomo for the regex.

Again, comments and patches (or better thought-out implementations) are welcomed and encouraged.

14 Replies to “A NAT-PMP client library for Python”

  1. Many thanks!

    I really needed this one 🙂
    I’m sure it would be useful for many python applications.
    Thanks again.

  2. One suggestion:
    put the send_request_with_retry calls inside a try-finally block.
    > addr_response = send_request_with_retry(…)
    > request_mutex.unlock()

  3. Hi anon,

    Thanks for the suggest/bug report. The mutex was left over from when I tried to do a simple thread-safe queue for requests, as per the spec. I decided to leave it for 0.0.2, and forgot to remove the half-baked attempt.

    I’ve removed it for now until the exception raising and handling code gets cleaned up a bit.

  4. Hi,

    I noticed the get_gateway_addr for nt systems is still TODO.
    I think the following pattern would work, the rest of the code should be exactly the same as the posix code. it works fine here.

    >pattern = re.compile(“.*?Default Gateway:[ ]+(.*?)\n”)

  5. There seems to be a bug in the client.

    If it fails to automatically get_gateway_addr() it throws an exception, even if you specify the gateway on the command line.

    It should not call get_gateway_addr() if -g is passed on the command line.

  6. Does this module return the list of all NAT-PMP ports added. For e.g.

    If i have a application which will add NAT-PMP port automatically, i want to check whether this port is added or not? How i can do this?

    1. No, because if you read the draft standard, you’ll notice that there is no “list all” operation in the NAT-PMP protocol. The two basic ops are “determine external address” and “map port”.

      In fact, the standard implies that if you want to determine whether a port is already mapped, you must send another map request. For example, you previously mapped private port 60000 to public port 50000, but lost state. Now you want to know what public port the server assigned previously for private port 60000. In this case, if you send a request to map private port 60000 to arbitrary port N, then you will receive a response containing the current public port mapping for that port, namely, 50000. If it wasn’t mapped, you’d receive the actual mapping you requested, namely N. After that, you can destroy the mapping by sending a request with lifetime 0 and external port 0.

      If you want to know what the server’s *public* port 50000 is mapped to, then it doesn’t look like there is an operation for that query in the protocol. If you find a way in the RFC, I’m happy to add a method or take a patch.

  7. Two years later…

    The client still contains a bug where it always calls get_gateway_addr() even if -g is passed on the command line. Worked around by hard-coding my gateway address into natpmp_client.py on line 21 (e.g., gateway = “”). I don’t know enough Python to make this conditional, or I’d just fix it for you.

    1. ah, my apologies. this is one of those cases where I fixed the bug locally and moved on, forgetting to distribute the modified copy.

      Fixed now, I believe. the 0.2.1 tarball contains the latest repository, which should no longer have this really irritating issue. And future bugs can be fixed by forking the Github repo ( https://github.com/yimingliu/py-natpmp ) and then contributing changes back to me :p

  8. Hey, a bit late, but thanks a lot. I really needed this, when I realized, my router for some reason can’t do port forwarding. But NAT PMP, works. So cheers.

Leave a Reply

Your email address will not be published. Required fields are marked *