The Portable SDK for UPnP* Devices (libupnp)

The GitHub project page is where all the real action happens.
The old Source Forge project page is linked here.

branch	status
main (22.1.x)
branch-2.0.x
branch-1.18.x
branch-1.14.x
branch-1.12.x
branch-1.10.x
branch-1.8.x
branch-1.6.x
branch-1.4.x

See LICENSE for details.

1. Overview
2. General Information
3. Changelog
4. Documentation
- 4.1. Quick Start
5. Other projects that are using the SDK
6. License Conditions
7. Release List
8. Package Contents
9. System Requirements
10. Build Instructions
- 10.1. Pre-requisites
- 10.2. CMake Build
11. Install/Uninstall Instructions
- 11.1. Install
- 11.2. Uninstall
12. New Features
13. Support and Contact Information
14. IXML support for scripting languages
15. SourceForge Badges
16. Thanks

1. Overview

The Portable SDK for UPnP™ Devices is an SDK for development of UPnP device and control point applications. It consists of the core UPnP protocols along with a UPnP-specific eXtensible Markup Language (XML) parser supporting the Document Object Model (DOM) Level 2 API and an optional, integrated mini web server for serving UPnP related documents. It provides developers with an API and open source code for building control points, devices, and bridges that are compliant with Version 1.0 of the Universal Plug and Play Device Architecture Specification and supports several operating systems like Linux, *BSD, Solaris and others.

2. General Information

UPnP™ is an architecture that enables discovery, event notification, and control of devices on a network, independent of operating system, programming language, or physical network connection. UPnP™ is based on common Internet standards and specifications such as TCP/IP, HTTP, and XML. For detailed information about UPnP™, including the UPnP™ Device Architecture Specification, please visit the Open Connectivity Foundation web site, which took over the UPnP™ Forum’s work in 2016.

In 2000, Intel created the first version of the Linux SDK for UPnP™ Devices and subsequently released it to the open source community to foster growth of UPnP™.

In 2006 this 100% compatible fork of the original project was created to support further development. This way, the project now continues using the name “Portable UPnP™” and as a project that is more open to contributions of the community. The main goal is the availability of the project for all important platforms to become a standard for UPnP™.

3. Changelog

4. Documentation

The documentation resides inside the source code itself and is generated by Doxygen. Documentation for each function resides in a comment section immediately preceding the function.

With Doxygen installed, build the docs from your build directory:

cmake --build . --target docs   # generates HTML under docs/doxygen/html/index.html

Note: the UPnP_Programming_Guide.pdf included in the docs/ directory is from version 1.2 and is outdated.

4.1. Quick Start

For a minimal, standalone example of how to use libupnp with CMake — independent of the repository’s own build system — see the community-maintained libupnp_example project. It demonstrates a simple SSDP client and shows how to write a CMakeLists.txt that uses find_package(upnp) to link against an installed copy of the library. It has been tested on Linux and Windows.

For a fuller reference covering a complete UPnP device and control point, see the samples/tv directory in this repository.

5. Other projects that are using the SDK

This is a list of some of the projects and products that are based on the SDK for UPnP™ Devices. Please let us know if you are working on a project and would like to see it listed here!

aMule has libupnp support to perform port forwarding.
Gerbera UPnP™ media server, the successor of MediaTomb.
libmcupnp is a Free UPnP(v1) library for easy “MediaServer:1 Client” implementations. The library is built on top of libupnp.
eMule Morph uses libupnp to forward ports automatically.
PeerStream Audio Video Server.
GeeXboX uShare™ A/V media server.
The Linux UPnP™ Internet Gateway Device This project is a daemon that emulates Microsoft’s Internet Connection Service (ICS). It implements the UPnP™ Internet Gateway Device (IGD) specification and allows UPnP™-aware clients, such as MSN Messenger, to work properly from behind a NAT firewall.
FreeBSD ports of both the SDK for UPnP™ Devices and the Linux UPnP™ IGD were contributed to the FreeBSD ports collection by Yen-Ming Lee.
IGD2 for linux is an updated version of Linux-IGD implementation. This new version is created on top of UPnP IGD:2 specifications available from https://openconnectivity.org/developer/specifications/upnp-resources/upnp/internet-gateway-device-igd-v-2-0.
gmrender-resurrect is a resource efficient UPnP/DLNA renderer, optimal for Raspberry Pi, CuBox or a general MediaServer. Fork of GMediaRenderer to add some features to make it usable.
Music Player Daemon uses libupnp to browse and play music stored on an UPnP Media Server.
VLC media player uses libupnp for services discovery.
Jami, the GNU distributed communication platform, uses libupnp to set up port forwarding on the local router.
RetroShare, an encrypted peer-to-peer messaging and file sharing platform, can use libupnp for port forwarding.
vdr-plugin-upnp turns the VDR video recorder into a UPnP™/DLNA media server.

6. License Conditions

The Portable SDK for UPnP™ Devices is distributed under the BSD (Berkeley Standard Distribution) license. This license allows you to use the source code royalty free and does not place any restrictions on what you do with source code derived from the SDK. For full details on the license conditions, please consult the LICENSE file located inside the SDK distribution.

7. Release List

Release Number	Date	History
22.1.8	2026-09-30	Portable UPnP SDK
22.1.7	2026-09-29	Portable UPnP SDK
22.1.6	2026-09-27	Portable UPnP SDK
22.1.5	2026-09-25	Portable UPnP SDK
22.1.4	2026-09-24	Portable UPnP SDK
22.1.3	2026-09-24	Portable UPnP SDK
22.1.2	2026-09-23	Portable UPnP SDK
22.1.1	2026-09-22	Portable UPnP SDK
22.1.0	2026-09-10	Portable UPnP SDK
22.0.6	2026-08-12	Portable UPnP SDK
22.0.5	2026-08-12	Portable UPnP SDK
22.0.4	2026-07-15	Portable UPnP SDK
22.0.3	2026-07-14	Portable UPnP SDK
22.0.2	NA	Internal
22.0.1	NA	Internal
22.0.0	NA	Internal
2.0.2	2026-06-17	Portable UPnP SDK
2.0.1	2026-06-17	Portable UPnP SDK
2.0.0	2026-06-16	Portable UPnP SDK
1.18.5	2026-04-22	Portable UPnP SDK
1.18.4	2026-03-27	Portable UPnP SDK
1.18.3	2026-03-16	Portable UPnP SDK
1.18.2	2026-03-10	Portable UPnP SDK
1.18.1	2026-03-01	Portable UPnP SDK
1.18.0	2026-02-09	Portable UPnP SDK
1.16.0	canceled	Portable UPnP SDK
1.14.31	2026-04-22	Portable UPnP SDK
1.14.30	2026-02-09	Portable UPnP SDK
1.14.29	2026-02-08	Portable UPnP SDK
1.14.28	2026-02-08	Portable UPnP SDK
1.14.27	2026-02-08	Portable UPnP SDK
1.14.26	2026-02-06	Portable UPnP SDK
1.14.25	2025-09-18	Portable UPnP SDK
1.14.24	2025-06-11	Portable UPnP SDK
1.14.23	2025-06-07	Portable UPnP SDK
1.14.22	2025-06-02	Portable UPnP SDK
1.14.21	2025-06-01	Portable UPnP SDK
1.14.20	2024-10-07	Portable UPnP SDK
1.14.19	2024-04-22	Portable UPnP SDK
1.14.18	2023-08-21	Portable UPnP SDK
1.14.17	2023-04-30	Portable UPnP SDK
1.14.16	2023-03-30	Portable UPnP SDK
1.14.15	2022-11-18	Portable UPnP SDK
1.14.14	2022-10-05	Portable UPnP SDK
1.14.13	2022-08-03	Portable UPnP SDK
1.14.12	2021-09-26	Portable UPnP SDK
1.14.11	2021-08-20	Portable UPnP SDK
1.14.10	2021-08-17	Portable UPnP SDK
1.14.9	2021-08-08	Portable UPnP SDK
1.14.8	2021-08-07	Portable UPnP SDK
1.14.7	2021-05-08	Portable UPnP SDK
1.14.6	2021-04-19	Portable UPnP SDK
1.14.5	2021-04-06	Portable UPnP SDK
1.14.4	2021-03-29	Portable UPnP SDK
1.14.3	2021-03-29	Portable UPnP SDK
1.14.2	2021-02-28	Portable UPnP SDK
1.14.1	2021-02-08	Portable UPnP SDK
1.14.0	2020-07-20	Portable UPnP SDK
1.12.1	2020-04-07	Portable UPnP SDK
1.12.0	2020-01-22	Portable UPnP SDK
1.10.1	2019-11-20	Portable UPnP SDK
1.10.0	2019-11-01	Portable UPnP SDK
1.8.7	2020-04-07	Portable UPnP SDK
1.8.6	2019-11-20	Portable UPnP SDK
1.8.5	2019-11-01	Portable UPnP SDK
1.8.4	2018-10-25	Portable UPnP SDK
1.8.3	2017-11-12	Portable UPnP SDK
1.8.2	2017-11-12	Portable UPnP SDK
1.8.1	2017-05-24	Portable UPnP SDK
1.8.0	2017-01-04	Portable UPnP SDK
1.6.25	2016-02-10	Portable UPnP SDK
1.6.24	2017-11-19	Portable UPnP SDK
1.6.23	2017-11-19	Portable UPnP SDK
1.6.22	2017-05-30	Portable UPnP SDK
1.6.21	2016-12-21	Portable UPnP SDK
1.6.20	2016-07-07	Portable UPnP SDK
1.6.19	2013-11-15	Portable UPnP SDK
1.6.18	2013-01-29	Portable UPnP SDK
1.6.17	2012-04-03	Portable UPnP SDK
1.6.16	2012-03-21	Portable UPnP SDK
1.6.15	2012-01-25	Portable UPnP SDK
1.6.14	2011-11-17	Portable UPnP SDK
1.6.13	2011-03-17	Portable UPnP SDK
1.6.12	2011-02-08	Portable UPnP SDK
1.6.11	2011-02-07	Portable UPnP SDK
1.6.10	2011-01-30	Portable UPnP SDK
1.6.9	2010-11-07	Portable UPnP SDK
1.6.8	2010-10-21	Portable UPnP SDK
1.6.7	2010-10-04	Portable UPnP SDK
1.6.6	2008-04-25	Portable UPnP SDK
1.6.5	2008-02-02	Portable UPnP SDK
1.6.4	2008-01-26	Portable UPnP SDK
1.6.3	2007-12-26	Portable UPnP SDK
1.6.2	2007-12-10	Portable UPnP SDK
1.6.1	2007-11-08	Portable UPnP SDK
1.6.0	2007-06-23	Portable UPnP SDK
1.4.6	2007-04-30	Portable UPnP SDK
1.4.5	2007-04-28	Portable UPnP SDK
1.4.4	2007-04-17	Portable UPnP SDK
1.4.3	2007-03-06	Portable UPnP SDK
1.4.2	2007-02-16	Portable UPnP SDK
1.4.1	2006-08-11	Portable UPnP SDK
1.4.0	2006-06-12	Portable UPnP SDK
1.3.1	2006-03-05	UPnP SDK for Linux
1.3.0	2006-03-04	UPnP SDK for Linux
1.2.1a	2003-11-08	UPnP SDK for Linux
1.2.1	2003-02-13	UPnP SDK for Linux
1.0.4	2001-08-15	UPnP SDK for Linux
1.0.3	2001-06-12	UPnP SDK for Linux
1.0.2	2001-02-07	UPnP SDK for Linux
1.0.1	2000-10-13	UPnP SDK for Linux
1.0.0	2000-08-31	UPnP SDK for Linux
0.9.1	2000-08-17	UPnP SDK for Linux
0.9.0	2000-08-01	UPnP SDK for Linux

8. Package Contents

The SDK for UPnP Devices contains the following:

Path/File	Description
README.md	This file. Contains the installation and build instructions.
COPYING	The licensing terms the SDK is distributed under.
ChangeLog	Changes and new features.
SECURITY.md	How to report security vulnerabilities.
docs	The Doxygen configuration, API change notes and the old programming guide.
ixml/inc	The public include files required to use the XML parser.
ixml/src	The source code to the XML parser library.
upnp/inc	The public include files required to use the SDK.
upnp/src	The source files comprising the SDK, libupnp.so.
samples/tv	A sample device and control point application, illustrating the usage of the SDK.
gtest	Unit tests based on GoogleTest.
tests	Python integration tests.
fuzzer	Fuzzing targets.

9. System Requirements

The SDK for UPnP Devices is designed to compile and run under several operating systems. It does, however, have dependencies on some packages that may not be installed by default. All packages that it requires are listed below.

Dependency	Description
libpthread	The header and library are installed as part of the glibc-devel package (or equivalent).

Additionally, the documentation for the SDK can be auto-generated from the upnp.h header file using Doxygen, a documentation system for C, C++, IDL, and Java*. Doxygen generates the documentation in HTML and LaTeX format, and the LaTeX output can be converted into a PDF file. To generate the documentation these tools are required:

Package	Description
Doxygen	The homepage for Doxygen is https://www.doxygen.nl/index.html. Doxygen is the only requirement for generating the HTML documentation.
LaTeX	To generate the PDF documentation, a LaTeX distribution such as TeX Live is necessary. Run `make` in the generated `docs/doxygen/latex` directory to build `refman.pdf` with pdflatex.

For the UPnP library to function correctly, networking must be configured properly for multicasting. To do this:

% ip route add 239.0.0.0/8 dev eth0

where ‘eth0’ is the network adapter that the UPnP library will use. Without this addition, device advertisements and control point searches will not function.

10. Build Instructions

10.1. Pre-requisites

Some packages/tools are required to build the library. Here’s a minimal ‘inspirational example’ that builds the library using a Docker Ubuntu image.

% docker run -it --rm ubuntu /bin/bash

% apt update \
  && apt install -y build-essential cmake pkg-config git \
  && git clone http://github.com/pupnp/pupnp.git \
  && cd pupnp \
  && cmake -B build

% cmake --build build

10.2. CMake Build

In Order to build everything using the cmake build system, you just need to install cmake for your platform. Standalone cmake is recommended, IDE’s like Visual Studio have built-in support which works, but as cmake in general encourages out-of-source builds and VS writes it’s config into the source, cmake-gui should be used on windows.

In addition to the standard CMake options, the following options are available:

DOWNLOAD_AND_BUILD_DEPS: This option is only available if a useable git program was found on your system. With this option on, the pthread4w package will be downloaded while configuring the build-env, then it will be build and installed along with upnp.
UPNP_ENABLE_TESTING: This option activates the unit tests.
UPNP_ENABLE_TESTING_INTEGRATION: This option activates the integration tests (find_package/add_subdirectory consumption checks).

If you don’t want to build pthreads4w in the same build as upnp, you can download it from https://github.com/Vollstrecker/pthreads4w. Just build and install it. The libs and headers will be found, if you set CMAKE_INSTALL_PREFIX (the base install dir) to the same location.

For information on general usage of the cmake build system see: https://cmake.org/cmake/help/v3.19/guide/user-interaction/index.html

11. Install/Uninstall Instructions

11.1. Install

After building, install the SDK as root with:

% cmake --install build

The destination is set by CMAKE_INSTALL_PREFIX at configure time, or by passing --prefix to cmake --install.

11.2. Uninstall

CMake does not provide an uninstall target. The installed files are listed in build/install_manifest.txt, so they can be removed, as root, with:

% xargs rm < build/install_manifest.txt

The manifest lists the installed paths without any DESTDIR prefix. Only use it after an install done without DESTDIR; after a DESTDIR install, remove that directory instead.

12. New Features

See ChangeLog file.

13. Support and Contact Information

Report bugs at https://github.com/pupnp/pupnp/issues, and ask questions at https://github.com/pupnp/pupnp/discussions. To report a security vulnerability, follow SECURITY.md instead of opening a public issue.

* Other brands, names, and trademarks are the property of their respective owners.

14. IXML support for scripting languages

The tree structure of XML documents created by IXML is hard to maintain when creating a binding for a scripting language. Even when many elements may never be used on the script side, it requires copying the entire tree structure once you start accessing elements several levels deep.Hence scriptsupport was added. To enable it compile while IXML_HAVE_SCRIPTSUPPORT has been defined (enabled by default). This allows control using only a list instead of a tree-like structure, and only nodes actually accessed need to be created instead of all the nodes in the tree.

Here’s how its supposed to work:

The scriptsupport allows you to add a callback when a node is freed on the C side, so appropriate action can be taken on the script side, see function ixmlSetBeforeFree().
Instead of recreating the tree structure, an intermediate object should be created only for the nodes actually accessed. The object should be containing a pointer to the node and a ‘valid flag’ which is initially set to TRUE (the valid flag, can simply be the pointer to the node being NULL or not). Before creating the intermediate object, the custom tag ‘ctag’ can be used to check whether one was already created.
the node object gets an extra ‘void* ctag’ field, a custom tag to make a cross reference to the script side intermediate object. It can be set using ixmlNode_setCTag(), and read using ixmlNode_getCTag(). Whenever a new intermediate object is created, the ctag of the corresponding node should be set to point to this intermediate object.
The tree structure traversal is done on the C side (looking up parents, children and siblings)
Every intermediate object created should be kept in a list (preferably a key-value list, where the key is the pointer to the node and the value is the pointer to the intermediate object)
when the callback is called, the node should be looked up in the list, the flag set to false, the pointer to the C-side node be cleared and on the C-side the ctag should be cleared.
whenever the intermediate object is accessed and its flag is set to False, an error should be thrown that the XML document has been closed.

Freeing resources can be done in 2 ways, C side by simply calling the free node methods, or script side by the garbage collector of the script engine.

Script side steps:

if the valid flag is set to False (XML document is closed), then the intermediate object can be destroyed, no further action.
if the node has a parent, then the intermediate object can be destroyed after the ctag on the corresponding node has been cleared. Nothing needs to be freed on the C-side.
if the node has no parent, then the node must be freed on the C side by calling the corresponding free node methods. This will result in a chain of callbacks closing the node and all underlying nodes.