aligungr/UERANSIM: a 5G-SA UE and gNodeB that simulates the radio over UDP

A 5G phone and a base station that talk to no radio

UERANSIM is an open source 5G UE and RAN implementation in C++. The project's own glossary is worth borrowing, because it defines the two sides in plain terms: a UE is a 5G mobile phone and a RAN, specifically a gNodeB, is a base station. The stated purpose is testing a 5G Core Network and studying the 5G System, and the project claims to be the first open source 5G-SA UE and gNodeB implementation.

The interesting decision is what the simulator leaves out. The status badges split the system into two halves, and the split is the whole story: the control plane is marked functional, the user plane is marked functional, and the radio interface is marked simulated. The prose behind the badges says the 5G-NR radio interface is partially implemented and simply simulated over the UDP protocol.

That single design choice shapes everything about the tool. You get the signalling and the payload path of a 5G-SA system, and you get a radio interface that is a stream of UDP packets rather than a waveform. For protocol work, that is usually the point. For anything that depends on propagation, scheduling across real radio resources or spectral behaviour, it is a hard boundary.

Functional is not the same as complete

The status section is honest in a way that many simulator projects are not. Basic functionalities of the UE and gNodeB are described as fully functional and ready to use, and then the very next sentence says that some of the features are not complete. The detail is delegated to a Feature Set page in the project wiki.

That delegation is both the strength and the weakness of the documentation. It means the feature matrix is maintained somewhere that can change without a code commit, which is useful for a living project. It also means the repository's README alone cannot tell you whether a specific 3GPP procedure is implemented. If your work depends on a particular message or procedure, the Feature Set wiki is the place to check before you plan the integration, not after.

The version context matters for the same reason. The badges describe the project as 3GPP R15, and the repository carries a `config/` directory, a `test/` directory, a `tools/` directory and a `CMakeLists.txt` alongside a plain `makefile`, so both a CMake and a make path exist in the tree. There is no release note in the repository text that maps features to the R15 baseline, so the Feature Set page remains the authority.

The documentation lives in the wiki, the binaries live in releases

There is a deliberate split in where the project's information lives. The README points to the UERANSIM Wiki for documentation and to the releases page for binaries, and it asks users to make sure they always have the latest UERANSIM. The repository carries no build or install tutorial, and no step by step setup guide for a fresh machine.

Practically, that means two paths. If you want a working simulator, you take a release from the releases page and run the binary for your platform, following the wiki for how to point the UE and the gNodeB at a 5G core. If you want to work on the simulator itself, you clone the repository and build it, and again the wiki carries the details rather than the README. Either way you are expected to read the wiki before you read anything else, so plan for that.

The advice to always use the latest release is not a marketing line, it is a practical instruction from a project whose feature set moves with each tag. The recent tags show a fairly steady line of work: v3.2.7 on 2025-02-11, v3.2.8 on 2026-04-15 and v3.3.0 on 2026-06-07, with the last push to the repository landing on 2026-10-14.

Dual licensed, and closed source use is the sensitive part

UERANSIM is under AGPL-3.0, but the licensing story is not just AGPL-3.0. The project states that all source code and related files, including documentation and wiki pages, are dual licensed with AGPL-3.0 and a commercial license, and the licence file in the repository is the place to read the terms.

The warning attached to that statement is specific and worth quoting for its meaning rather than its phrasing: closed source commercial usage may not be permitted with the AGPL-3.0, and if that licence is not compatible with your use case the project asks you to contact the listed address to buy a commercial licence. In other words, a vendor shipping a product that links to or embeds UERANSIM has two paths, and one of them requires a purchase conversation.

Two practical consequences follow. First, read the LICENSE file in the repository rather than relying on the licence label alone, because the dual licensing arrangement is the operative fact. Second, the network access clause of AGPL-3.0 is the part that most often matters for a simulator used inside a company network, and this article does not interpret what the obligations are for your deployment. Determining that is a question for whoever owns your compliance obligations, and the commercial licence route exists precisely for organisations that have decided the AGPL terms do not work for them.

Where UERANSIM is the wrong instrument

The clearest wrong case is any question that requires the physical layer. Since the radio interface is simulated over UDP, UERANSIM cannot tell you anything about modulation, coding, signal strength, interference, handover behaviour under real radio conditions or capacity in a real cell. The project says this directly, and it also flags that some features are not complete, so the boundary is not a vague limitation but a stated design position.

A second wrong case is a 5G core network test that needs a realistic radio load. Because the gNodeB side is a simulator rather than an instrumented base station, the traffic you can push through it is not equivalent to real RAN behaviour, and a test result from UERANSIM should be read as a protocol conformance result rather than as a performance result.

The alternative approach, if you need the other half, is a hardware or commercial RAN setup where the radio interface is genuine and the UE is a real device or a vendor instrument. The difference in approach is exactly that boundary: the physical layer is real, so you gain RF behaviour and realistic scheduling while giving up the open, scriptable, free access to signalling internals that makes UERANSIM useful in the first place. For protocol study, automated regression and core network integration, the open simulator wins. For anything radio, it is not a substitute.

The project shape tells you it is a working tool, not a research prototype

Looking at the repository layout gives a reasonable picture of what kind of project this is. Beyond the source in `src/`, there is a `config/` directory, a `test/` directory, a `tools/` directory, a `CMakeLists.txt`, a `makefile`, a `.clang-format` file, a `CONTRIBUTING.md` and a `.github/` directory. Continuous integration, a formatter configuration and a separate test tree are the marks of a project that expects outside contributions, and the project actively invites pull requests.

Two limits of the public text are worth naming. The repository text does not list the individual upstream 5G core projects it is designed to talk to, nor does it document the configuration schema that `config/` holds, so the wiki is where you will find how the UE and gNodeB are told which core to register with. The README also carries no performance figures at all, which is consistent with a project whose physical layer is simulated and which therefore declines to present numbers that would only describe the host machine.

The last push was on 2026-10-14, and the repository is not archived, so the code is still moving. Tag names and release dates are the signal to watch for your own upgrade planning, since the README asks users to run the latest release rather than a pinned one.

Editorial conclusion

Adopt UERANSIM when you need a 5G-SA user equipment and a gNodeB to exercise a 5G core network, study the 5G System or automate protocol level tests, and you can live with a radio interface that exists only as UDP traffic. Do not adopt it for radio planning, RF behaviour, handover performance or anything that needs a real physical layer, because the project states the 5G-NR radio interface is only partially implemented and simulated. Verify first which 3GPP release features you actually need against the Feature Set wiki page, since the project says some features are incomplete, and confirm the licence route before you start, because closed source commercial use may not be permitted under AGPL-3.0 and requires a commercial licence from the author.

Frequently asked questions

Official sources

1. aligungr/UERANSIM on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases