ns-3 is a discrete event network simulator that Python can drive

A simulator for people who cannot use the real network

ns-3 is a free open source project aiming to build a discrete event network simulator targeted for simulation research and education, and the project says plainly that it is collaborative, hoping that the missing pieces of the models it has not yet implemented will be contributed by the community in an open collaboration process. The use case is specific. When you are designing a protocol change, studying congestion behaviour, or teaching a class, the alternatives are a live testbed, which is slow, expensive and risky, or a simulator, which is fast, free and reproducible. That is the whole argument. The audience is researchers and students, and the framing in the project is about participation rather than consumption. The GitHub repository is a read only mirror kept in sync with the main GitLab repository, and the project asks you explicitly not to file pull requests there, instead filing issues and merge requests on GitLab, which is a small but important operational detail if you plan to contribute.

C++ libraries with Python bindings on top

From a software perspective, ns-3 consists of a number of C++ libraries organised around different topics and technologies, and simulation programs can be written in either C++ or Python, with Python enabled by runtime C++ and Python bindings. A simulation program will typically link or import the ns core library and any additional libraries it needs. The requirement is a modern C++ compiler, g++ or clang++, and the CMake build system, and most ns-3 programs are single threaded, with some limited support for parallelisation through the MPI framework. There is also a mode the project does not mention much, which is real time emulation, where ns-3 binds to an Ethernet device on the host machine and generates and consumes packets on a real network, which is a genuinely different use from simulation. The APIs are documented with Doxygen. The library layout follows from the design, with the src directory holding the libraries maintained by the project, the contrib directory being where third party libraries are usually added, and a bindings/ directory for the language bindings. There is also a doc/ directory, an examples/ directory with topics such as routing, energy, error-model, ipv6, matrix-topology, realtime, tcp, udp, wireless, traffic-control and tutorial, plus a test.py at the root and a build-support/ directory.

Two source archives, and why the difference matters

ns-3 can be obtained either by downloading a released source archive or by cloning the project's Git repository, and since release 3.45 there are two source archives published with each release. The first is the plain archive of the same code you get by checking out the release tag, and the second bundles additional contributed modules. That distinction is the kind of detail that trips people up, so it is worth being precise about what the second archive contains. Those extra modules are maintained outside the main open source project, but they have been reviewed by maintainers and lightly tested for compatibility with the release. The set will change over time as new third party libraries appear, and modules may also drop out as they lose compatibility with the mainline, for instance if they become unmaintained. So the allinone archive is a convenience with a moving membership, not a stable superset, and if you depend on a specific contributed module you are better off pulling it into contrib yourself and controlling the version. The project's own site at nsnam.org holds substantially more information than these documentation excerpts, and the full tutorial lives in the documentation at the latest documentation path.

The ns3 tool wraps CMake in a friendlier API

The build deserves its own explanation because it is where newcomers lose an afternoon. ns-3 uses CMake, but the project maintains a customised wrapper around it called the ns3 tool, which provides a Waf-like API to the underlying CMake build manager, and you are expected to use that wrapper rather than calling CMake directly. You configure first, because the configuration step is what sets the build options such as whether to enable the examples and the tests:

./ns3 configure --enable-examples --enable-tests

Then you build:

./ns3 build

By default the build artefacts land in the build/ directory. The wrapper exists because the raw CMake interface for a project with this many optional modules and a Python packaging path is unpleasant, and the project has invested in a small command line that hides it. Detailed instructions on using the ns3 tool are in the quick start guide in the documentation. The Python packaging path is a separate and more modern layer on top. The build system definition in the repository shows that the Python package is not a separate implementation but a packaging of the same C++ code: the build backend is setuptools with cmake-build-extension, setuptools_scm provides the version, and the setup script defines a CMakeExtension named BuildAndInstall with configure options that turn on assertions, logging, Python bindings, optional component fetching and pip packaging, and pass the paths of the currently running Python so that CMake finds the right components. The release version of the project is maintained separately, with a release notes file and a VERSION file at the root.

Testing, running a sample, and reading the traces

ns-3 contains test suites to validate the models and detect regressions, and the command to run them is short:

./test.py

More detail is in the test framework section of the manual. Running an example is equally direct, and the documented one on recent Linux systems is:

./ns3 run simple-global-routing

That program generates a simple-global-routing.tr text trace file and a set of simple-global-routing binary PCAP trace files, and the documentation tells you those PCAP files can be read with tcpdump using the flags for no name resolution, unix style timestamps and reading a named file. The source of the example lives in the examples/routing directory, so you can read the code that produced the trace. That combination, a runnable example whose source is short enough to read and output that opens in an existing packet analyser, is what makes ns-3 usable as a teaching tool as well as a research one. The supported platform list is in the release notes file, and the project is candid that other platforms may or may not work and that patches to improve portability are welcome.

Running from Python is the shortcut, and it has a cost

The documented shortcut is that if you do not plan to modify ns-3 upstream modules, you can get a pre-built version of the ns-3 Python bindings, and the project recommends creating a Python virtual environment to isolate the packages from system wide ones:

python3 -m venv ns3env
source ./ns3env/bin/activate
pip install ns3

The condition in that sentence is the important part, because it defines the two modes of use. If you are only writing simulation scenarios against the existing models, the pip route gets you a working environment quickly. If you intend to modify ns-3 itself, you are back to the source build with the ns3 tool and CMake, and the Python route does not help you. There is a deeper architectural point too. The bindings are runtime C++ and Python bindings, which means Python is a scripting layer over a C++ core rather than a reimplementation, and the pyproject configuration pins cppyy at version 3.5.0 as the binding layer. That has a consequence for how you think about performance. Simulation programs are mostly single threaded, and the parallelisation support through MPI is described as limited, so a large scenario is a matter of how you configure the simulation rather than how you spread it across cores.

Editorial conclusion

Adopt ns-3 if you are researching network protocol behaviour, teaching it, or evaluating designs where a real testbed would be too slow, too expensive or too risky, and you are prepared to compile the code yourself rather than install a package. Do not adopt it if you need to measure live production traffic, since it is a simulator and not a monitoring tool, and do not expect a Python only workflow, because the default path builds C++ and the bindings sit on top of it. Before you start, read the quick start guide, check the platform list in the release notes for your operating system, and plan on configuring the build with examples and tests enabled so that the sample programs are available.

Frequently asked questions

Official sources

1. Issues
2. nsnam/ns-3-dev-git on GitHub
3. Project website
4. README