UPnP PortMapper: managing router port forwards from the desktop

The router's own web interface, without the web interface

UPnP PortMapper is an easy to use program that manages the port mappings of a UPnP enabled internet gateway device, which is a router, in the local network. You can view, add, and remove port mappings through it.

The reason it exists is spelled out in the README. Port forwarding makes it possible to reach servers running in a private network from the internet, and the examples given are SSH, web, and game servers. The same thing can be done through the web administration interface of a router, but using PortMapper is much more convenient, because you create a new preset or select an existing preset and click one button, and the IP address is retrieved automatically.

That last detail is the whole value proposition. A router's own interface asks you to type the internal IP address of the machine you are on, and that address changes when your laptop rejoins the network, so every mapping you created by hand is eventually a mapping that points at the wrong machine. The tool looks the address up, which removes the most common way a hand made port forward goes wrong.

The interface is written in English and German, and PortMapper automatically selects the language according to your operating system, so there is nothing to configure on that front.

The project is Java, licensed under GPL-3.0, and it is not archived, with the last push on 2026-07-01. The releases are 2.2.4 from 2024-09-14, whose note is that dependencies were upgraded, v2.2.3 from 2023-03-19, which fixed the font size of the log panel, and v2.2.1 from 2020-07-11, a set of minor bug fixes.

Binaries are downloaded from SourceForge, and the project is also published to Maven Central under the group and artifact com.github.kaklakariada with the artifact name portmapper, which is how you would pull it into a build of your own.

Presets, and the address you never have to type

The workflow the README describes is a two step one for a common case. You pick a preset, or define a new one, you click a button, and the mapping appears on the router.

The interesting engineering is in the IP address retrieval. A port mapping on a router is a triple, an external port on the router, an internal port, and an internal IP address that identifies the machine behind the router. Almost every home router interface makes you supply all three, and the third is the one that changes.

The tool handles it, which is why it is a desktop application rather than a script. A script that shells out to a router's UPnP endpoint would have to determine the local address the same way, and doing that correctly means enumerating the interfaces, discarding the loopback and the virtual ones, and picking the address on the subnet that matches the gateway. Doing that in the GUI is a detail the user never sees, and doing it in a script is a problem you have to solve.

The other thing a GUI gives you is a view of the existing mappings. The README says you can view, add, and remove them, and a list of what is currently open is the thing that most router interfaces show worst. With a tool like this, the list of open ports on your own network is a table you can read, and removing a mapping is a click on the row you no longer need.

That matters because port mappings accumulate. Every manual experiment, every temporary test server, and every abandoned project leaves an entry behind, and the router's own interface rarely makes it easy to see the whole list at once. The tool is as much about cleaning up as about opening the port.

Running it, and the two builds that catch people out

The requirements are a JRE 11 or later, and the README recommends the latest OpenJDK JRE from AdoptOpenJDK, which is now the Temurin distribution. On Windows it suggests the msi installer, because that sets the JAVA_HOME environment variable and adds Java to the PATH for you.

You check the installation with the usual command.

java -version

And you run the application by double clicking the jar, or from the command line.

java -jar portmapper.jar

If you are still on Java 1.8 and cannot move to Java 11, the README points at PortMapper version 2.1.1, which is the last release that supports it.

The two builds are the second trap, and it is the one the troubleshooting section devotes the most space to. A jar you download from SourceForge includes its dependencies, but a jar you build yourself may not, and the symptom is a stack trace about a missing SLF4J logger factory at the very start of the program. The fix is documented in two ways. You can download the distribution build from SourceForge. Or, if you are building, you can run the project directly with the Gradle wrapper, or build it and run the jar whose name carries the all suffix, which includes every dependency.

  * Build and execute PortMapper using a single command `./gradlew run`

  * Build PortMapper using command `./gradlew build` and execute JAR `*-all.jar` that includes all dependencies: `java -jar build/libs/portmapper-$version-all.jar`

The repository carries a Gradle wrapper with both the shell and the Windows batch script, and a build.gradle at the root, so a from source build needs nothing installed beyond a JDK.

The troubleshooting section is the real documentation

Most of this README is about how the program fails, and that is unusual and useful. Four failures get their own sections.

The first is the JNI error, an error dialog with the message that a JNI error has occurred, which appears when you double click the jar. The second is the UnsupportedClassVersionError, which you get from the command line, and the message names the numbers: the class has been compiled by a more recent version of the Java runtime, class file version 55.0, while the runtime only recognises class file versions up to 52.0. The diagnosis in the README is that your Java version is outdated, and the fix is to install Java 11 or later, or to point at the full path of the java executable, quoting a path like the one under the AdoptOpenJDK directory.

The third is the PowerShell argument problem, which produces a class not found error for the main class .language=en. The cause is that PowerShell mangles a system property argument like -Duser.language=en, and the fix is to enclose the system property in double quotes.

java "-Duser.language=en" -jar portmapper.jar

That one is worth knowing before you hit it, because the error message points at the class name rather than at the shell.

The fourth is the missing dependency case described above, and the instruction there is to create a ticket with the complete error message and stack trace if the suggested fixes do not help.

Under the general troubleshooting heading there are two more that are not about Java at all. Update the firmware of your router to the latest version, and verify that your router supports UPnP and that it is enabled in the settings. Both are the first things to check with a router problem, and both are things a user with a Java error in front of them would not think to try.

When the router is not found

There is a whole section on the most common functional problem, which is that the tool cannot find the router at all, and the list of causes is the most technically interesting part of the README.

First, check whether the router supports UPnP and whether it is activated in the router's settings. Second, use a different UPnP library in the settings, with the note that the DummyRouterFactory is just for testing and is not a real implementation. Third, check whether a network bridge is active on your computer, and deactivate it if it is, because a bridge may prevent detection of the router, with a link to the bug report for that case.

That third point is the interesting one, and it points at the reason this class of tool can be flaky. UPnP discovery works by multicast on the local network, and a bridge, a virtual machine network, a container network, or a VPN can all sit between the client and the multicast traffic that carries the discovery response. The tool talks to the router the same way any UPnP device does, so it inherits the same fragility.

The settings also offer a log level, and the README says to set it to TRACE, connect again, and read the log. That is the diagnostic step that tells you whether the tool sent a discovery request and got nothing, or found something and failed later, and those are very different problems.

The last fallback is to skip discovery. If you can connect to the router from one device but not from another, you can specify the location URL directly, and the README notes that this is only supported for the weupnp library, which is selected with a library flag. You get the location URL from the machine that can reach the router by clicking the Info button.

That constraint, one library only, is a reasonable limitation for a fallback path, and it is also an honest one to know before you plan to use it.

Where the project stands, and the licence to keep in mind

Three things to note about the state of the project and the terms of using it.

The first is the release rhythm. The last three releases are 2.2.4 in September 2024, which upgraded dependencies, v2.2.3 in March 2023, which fixed the font size of the log panel, and v2.2.1 in July 2020, a set of minor bug fixes. The last push to the repository was on 2026-07-01, so there has been recent activity even though the newest tagged release is a couple of years old.

The second is the engineering signals in the repository. There is a Java CI workflow badge, and SonarCloud badges for the quality gate status and for coverage, which means the project is measured on both. The repository layout is a conventional Gradle Java project with a src directory for the code, a lib directory for the bundled libraries, a config directory, a doc directory, an Eclipse settings directory, and a Visual Studio Code settings directory.

The third is the licence, and it is the thing to weigh before you deploy this on a network. The project is licensed under GPL-3.0, and the repository carries a LICENSE file, while the README itself does not restate the terms, so the file is the place to read.

More practically, there is a question about the tool itself that no licence addresses. UPnP is, by design, unauthenticated, and any program on your local network can ask the router to open a port. That is why UPnP is disabled by default on many routers, and enabling it to run a port mapper means enabling it for everything on the network. The tool is convenient and honest about that, but the convenience comes at the cost of the same exposure, and that is a decision about your network rather than about this program.

The practical recommendation is the narrow one. Use it on a network you control, for mappings you can justify, and turn the mapping off when the test server is finished rather than leaving it open for the convenience of the next time.

Editorial conclusion

UPnP PortMapper fits a home lab or a small office where you want to open a port to a home server without the detour through a router's own administration pages, and where UPnP is already enabled. It does not fit a network where UPnP is disabled for good reason, since the protocol is unauthenticated and any program on the LAN can open ports on it, and it does not fit a server without a desktop. Verify first that your router has UPnP turned on and that you are on a JRE 11 or newer, since the class file version error in the troubleshooting section is the most common failure, that the LAN you are on is one where opening a port is intended, and that the port mapping you create is one you can defend to the people who use that network.

Frequently asked questions

Official sources

1. Issues
2. kaklakariada/portmapper on GitHub
3. License: GPL-3.0
4. README
5. Releases