Important Note: As of March 7, 2023, this information has migrated to a new manual-- the Installation guide linked from the main documentation page. You can read the below for historical interest, but it is probably stale information. Show
This wiki page used to be the installation guide for ns-3. ContentsSupported platformsns-3 is primarily developed on GNU/Linux and macOS platforms, and the minimal requirements to run basic simulations are a C++ compiler; either g++ or clang++ compiler, build system (CMake and either make or ninja), and Python (version 3) interpreter. The below instructions are per-platform instructions for supplemental packages that enable optional features of ns-3 or companion tools. Operating system and compiler supportns-3 is supported and currently tested on the following primary platforms:
The minimum Python version supported is currently version 3.6 or greater (major version 3). By supported, we mean that the project tries to support most or all of the build options on these platforms unless there is a good reason to exclude the option; and at least the debug build will compile. If you intend to do serious work using ns-3, and are forced by circumstances to use a Windows platform, consider virtualization of a popular Linux platform or using Windows Subsystem for Linux. Some aspects of ns-3 depend on Unix (or specifically Linux) support, such as the emulation or TapBridge features, and those components are not enabled on the Windows or MacOS versions cited above. Additional maintainers are invited to make more platforms, compilers and environments supported. Integrated development environment supportPlease see on configuring IDEs. EclipseThe Eclipse IDE is not an officially supported platform, but some developers use it and have compiled a HOWTO. NetBeansNetBeans is not officially supported either, but there is a HOWTO as well. QtCreatorSame rule applies to Qt Creator; it's not officially supported, but there are developers that use it and HOWTO is available. Support for optional featuresThere are a few options that are not enabled by default and are not available on all platforms. At the end of the configuration process (explained below), the status of these options are shown as detected by a waf or ns3 script: Summary of optional NS-3 features: Python Bindings : not enabled (Python library or headers missing) BRITE Integration : not enabled (BRITE not enabled (see option --with-brite)) NS-3 Click Integration : not enabled (nsclick not enabled (see option --with-nsclick)) GtkConfigStore : not enabled (library 'gtk+-2.0 >= 2.12' not found) XmlIo : not enabled (library 'libxml-2.0 >= 2.7' not found) Threading Primitives : enabled Real Time Simulator : enabled Emulated Net Device : not enabled (<netpacket/packet.h> include not detected) Network Simulation Cradle : not enabled (architecture None not supported) MPI Support : not enabled (option --enable-mpi not selected) NS-3 OpenFlow Integration : not enabled (OpenFlow not enabled (see option --with-openflow)) SQlite stats data output : not enabled (library 'sqlite3' not found) Tap Bridge : not enabled (<linux/if_tun.h> include not detected) PyViz visualizer : not enabled (Python Bindings are needed but not enabled) Use sudo to set suid bit : not enabled (option --enable-sudo not selected) Build tests : not enabled (defaults to disabled) Build examples : not enabled (defaults to disabled) GNU Scientific Library (GSL) : not enabled (GSL not found) Generally if the platform is missing some requirement for an option it is marked as "not enabled." Note that "disabled by user request" will be shown when the user explicitly disables a feature (such as "--disable-python"); and if a feature defaults to disabled this will also be noted (e.g., option --enable-sudo not selected). The table below is meant to help sort out the different features and on which platforms they are supported. This table reflects the status as of ns-3.15 and may have changed since then: Option status Option Linux FreeBSD Mac OS X Optimized build Y Y Y Python bindings Y Y Y Threading Y Y Y Real-time simulator Y Y Y Emulated Net Device Y N N Tap Bridge Y N N Network simulation cradle Y1 ? N Static builds Y Y Y Key: Y = supported; N = not supported; ? = unknown; dev = support in ns-3-dev (next release) Notes:
Using older version of ns-3 on newer systemsIt can be the case that trying to use an old version of ns-3 on a newer system can lead to warnings or errors because the compilers have become more strict over time. The below wiki page has some suggestions to work around this. https://www.nsnam.org/wiki/HOWTO_build_old_versions_of_ns-3_on_newer_compilers Using newer version of ns-3 on older systemsConversely, it can be the case that a user has an old version of Linux but newer compilers and libraries are needed to run the latest versions of ns-3. This blog has some recommendations on how to use chroot jails to work around this: https://www.projectguideline.com/installing-ns3-35-in-debian-10-chroot-jail-under-debian-11-host-os-or-any-version-of-linux-host/ PrerequisitesThe core of ns-3 requires a gcc/g++ installation of 4.9 or greater (Linux), or a recent version of clang compiler (OS X, Linux, or BSD), and Python 3.5 or greater. As mentioned above, different options require additional support. This is a list of packages (for Debian/Ubuntu systems) that are needed to support different ns-3 options. Note that other distributions (e.g., Fedora, FreeBSD) may have different package names or capitalization (e.g. ImageMagik). Installation should be similar for Red Hat/Fedora based systems, with "yum" replacing "apt-get", but some differences exist, so below is a guide for both Ubuntu (should generally apply to Debian) and Fedora/RedHat-based systems: LinuxUbuntu/Debian/MintThe following list of packages should be accurate through the Ubuntu 22.10 release; other releases or other Debian-based systems may slightly vary. Ubuntu 16.04 LTS release is probably the oldest release that is known to work with the most recent ns-3 releases. The list of packages depends on which version of ns-3 you are trying to build.
apt install g++ python3 cmake ninja-build git Git is not required if you are only downloading a source archive. Ubuntu comes with 'make' build tool, but if you are missing it (possibly on some other Debian-based distribution), you may want to install make or ninja-build. ninja is an alternative to make.
Ccache is a compiler cache optimization that will speed up builds across multiple ns-3 directories, at the cost of up to an extra 5 GB of disk space used in the cache. apt install ccache Note: For Ubuntu 20.04 release and earlier, the version of ccache provided by apt (3.7.7 or earlier) may not provide performance benefits, and users are recommended to install version 4 or later, possibly as a source install. For Ubuntu 22.04 and later, ccache can be installed using apt.
apt install g++ python3
apt install g++ python2 Note: As of ns-3.30 release (August 2019), ns-3 uses Python 3 by default, but earlier releases depend on Python 2 packages, and at least a Python 2 interpreter is recommended. If working with an earlier release, one may in general substitute 'python' for 'python3' in the below (e.g. install 'python-dev' instead of 'python3-dev'). Note: As of January 2022 (ns-3.36 release and ns-3-dev), the minimum g++ version is g++-8. Older Ubuntu releases (18.04, 16.04) come with an older default g++. On Ubuntu 18.04, this StackOverflow answer can be followed to install and prefer g++-8: https://askubuntu.com/a/1028656. On older Ubuntu such as 16.04, to use the most recent code, you must install g++-8 or g++-9 from the Ubuntu toolchain: https://launchpad.net/%7Eubuntu-toolchain-r/+archive/ubuntu/test The remaining are needed for optional ns-3 components.
python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3
apt install g++ python3 python3-dev pkg-config sqlite3 cmake
apt install python3-setuptools git
apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools Note: For Ubuntu 20.10 and earlier, the single 'qt5-default' package suffices apt install qt5-default
apt install g++ python3 cmake ninja-build git 0
apt install g++ python3 cmake ninja-build git 1
apt install g++ python3 cmake ninja-build git 2
apt install g++ python3 cmake ninja-build git 3
apt install g++ python3 cmake ninja-build git 4
apt install g++ python3 cmake ninja-build git 5 Note: clang-format-14 through clang-format-16 version is required.
apt install g++ python3 cmake ninja-build git 6
apt install g++ python3 cmake ninja-build git 7
apt install g++ python3 cmake ninja-build git 8 Note: Sphinx version >= 1.12 required for ns-3.15. To check your version, type "sphinx-build". To fetch this package alone, outside of the Ubuntu package system, try "sudo easy_install -U Sphinx".
apt install g++ python3 cmake ninja-build git 9 If the above doesn't work (doesn't detect GSL on the system), consult: https://coral.ise.lehigh.edu/jild13/2016/07/11/hello/. But don't worry if you are not using 802.11b models.
apt install ccache 0
apt install ccache 1
apt install ccache 2
apt install ccache 3 and you will want to install castxml and pygccxml as per the instructions for python bindings (or through the bake build tool as described in the tutorial). The 'castxml' and 'pygccxml' packages provided by Ubuntu 18.04 and earlier are not recommended; a source build (coordinated via bake) is recommended. If you plan to work with bindings or rescan them for any ns-3 C++ changes you might make, please read the chapter in the manual on this topic. Note: Ubuntu versions (through 19.04) and systems based on it (e.g. Linux Mint 18) default to an old version of clang and llvm (3.8), when simply 'libclang-dev' and 'llvm-dev' are specified. The packaging on these 3.8 versions is broken. Users of Ubuntu will want to explicitly install a newer version by specifying 'libclang-6.0-dev' and 'llvm-6.0-dev'. Other versions newer than 6.0 may work (not tested).
apt install ccache 4
apt install ccache 5
apt install ccache 6 Fedora/RedHatNote: This has not been updated for ns-3.37 release yet. The following list of packages should be aligned with recent Fedora releases; other releases may slightly vary. Note that these distributions sometimes change the package structure over time. Important: If you are using RedHat or CentOS, either versions 6 or 7, the default compilers are too old to build recent ns-3 releases. You must upgrade gcc and g++ to a more recent version. See below. Fedora and virtual machines The Waf build system can use several GB of space on /tmp when building ns-3. Fedora and RedHat have chosen to mount /tmp on tmpfs, sized at half of the RAM by default. On a virtual machine, where possibly as little as 4GB of RAM may be configured, this will lead to a 2GB /tmp partition and the ns-3 build will fail with a message such as: apt install ccache 7 One workaround is to increase your tmpfs size, such as (as root user): apt install ccache 8 This resizing must be done upon each reboot, and you should ensure that you have a swap partition also configured. Release-specific issues
Required and optional packages
apt install ccache 9
apt install g++ python3 0
apt install g++ python3 1
apt install g++ python3 2
apt install g++ python3 3
Prior to ns-3.29, use GTK+ version 2: apt install g++ python3 4 Starting with ns-3.29, use GTK+ version 3: apt install g++ python3 5
apt install g++ python3 6
apt install g++ python3 7
apt install g++ python3 8
apt install g++ python3 9
apt install g++ python2 0
apt install g++ python2 1
apt install g++ python2 2
apt install g++ python2 3 Steve Smith notes that the shell must be restarted after environment-modules package is installed, since environment-modules modifies the bash initialization scripts to enable the module command. Then, to find the programs mpic++ and mpiexec, one must do: apt install g++ python2 4 and then the commands should be found by the shell: apt install g++ python2 5 Steve Smith also noted problems with Fedora machines that do not have APX support, such as virtual machines: https://gitlab.com/nsnam/ns-3-dev/-/issues/397 Solution for those machines is to switch to mpich: apt install g++ python2 6
apt install g++ python2 7
apt install g++ python2 8
apt install g++ python2 9
python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 0 and you will want to install castxml and pygccxml as per the instructions for python bindings (or through the bake build tool as described in the tutorial). If you plan to work with bindings or rescan them for any ns-3 C++ changes you might make, please read the chapter in the manual on this topic.
python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 1 macOSmacOS installation of ns-3 relies on the Xcode command line tools provided by Apple, and the clang/llvm compiler used therein. A third-party package manager such as Homebrew can be used for optional extensions to ns-3 such as libxml2. The current version of macOS is 'Catalina' (10.15) and the version of Xcode is 11.2, as of this writing. If you are having problems with ns-3.29 and macOS, please look at the Errata page for some hints, or consider to use the development version (ns-3-dev) of ns-3 which should work now. ns-3.30 is not know to have macOS issues. The main steps to follow to prepare your macOS machine for a base ns-3 install (Xcode tools, and Python) are as follows:
At this point, you will likely be able to compile the main C++ libraries. The current macOS Catalina release ships with a basic Python 3 interpreter (version 3.7.3) which is enough to run the Waf build system but not much else. To use Python bindings or other Python features, a fuller install of Python is recommended. Visit https://www.python.org/downloads/mac-osx/ to download a Python 3 release (recommended), or else, if you prefer, use Homebrew or some other package manager to install a Python development environment. At this point, you should be able to use ns-3 in C++ or Python programs. The following options are available to add some additional libraries for more ns-3 features. In general, a third-party installer like Homebrew or MacPorts is needed:
. Note to Anaconda users: If you have installed Anaconda, you may encounter a build problem such as: python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 2 This can be worked around by configuring Waf to use the system Python instead of the Python version provided by Anaconda. At the Waf configuration stage, try: python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 3 When using build.py, the argument can be passed as follows: python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 4 See: issue 2778 in the ns-3 tracker for more information. WindowsFor Windows 10, there are two main options. Both involve using a Linux environment from within Windows. ns-3 is not compatible with the Windows Visual Studio compiler and IDE (there have been a few efforts to add Visual Studio support, but they have been abandoned).
Below is some other older (possibly out-of-date) information regarding Windows:
InstallationInstallation with BakeBake is a new tool for installing, building and finding out the missing requirements for ns-3 in your own environment. To use Bake you need to have at least Python (2.7 or above) and Git in your machine (see the section Prerequisites above to see how to install these). First you need to download Bake using Git, go to where you want Bake to be installed and call python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 5 It is advisable to add bake to your path. python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 6 After that you can use Bake to find the missing packages, download build and install ns-3 and its modules. To find out what is missing in your system and may be needed for installing ns-3 you can call bake check: python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 7 You should have seen something like: python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 8 Before downloading and building ns-3 you need to configure bake to inform it which are the modules you want added to ns-3, the standard distribution for example. python3 -m pip install --user cppyy apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 9 Then to see the modules it has added, and the specific system requirements for this configuration, you can call bake show: apt install g++ python3 python3-dev pkg-config sqlite3 cmake 0 To download the modules, build and install you can call bake deploy apt install g++ python3 python3-dev pkg-config sqlite3 cmake 1 This will download the selected modules, all their dependencies and build ns-3 with all these independent modules. You can also perform this installation step by step, i.e. by calling download and build in different steps. apt install g++ python3 python3-dev pkg-config sqlite3 cmake 2 Manual installationThe ns-3 code is available in Mercurial repositories on the server http://code.nsnam.org (look for the latest release e.g., "ns-3.26"). You can download a tarball of the latest release at http://www.nsnam.org/releases or you can work with our repositories using Mercurial. We recommend using Mercurial unless there's a good reason not to (See the end of this section for instructions on how to get a tarball release). The simplest way to get started using Mercurial repositories is to use the ns-3-allinone environment. This is a set of scripts that manages the downloading and building of various subystems of ns-3 for you. We recommend that you begin your ns-3 adventures in this environment as it can really simplify your life at this point. Downloading ns-3 Using GitOne practice is to create a directory called repos in one's home directory under which one can keep local Git repositories. If you adopt that approach, you can get a copy of ns-3-allinone by typing the following into your Linux shell (assuming you have installed Git): apt install g++ python3 python3-dev pkg-config sqlite3 cmake 3 As the git command executes, you should see something like the following displayed, apt install g++ python3 python3-dev pkg-config sqlite3 cmake 4 After the clone command completes, you should have a directory called ns-3-allinone under your ~/repos directory, the contents of which should look something like the following: apt install g++ python3 python3-dev pkg-config sqlite3 cmake 5 Notice that you really just downloaded some Python scripts and not yet the C++ code. The next step will be to use those scripts to download and build the ns-3 distribution of your choice. If you go to the following link: https://gitlab.com/nsnam/ you will see a number of repositories. Many are the private repositories of the ns-3 development team. The repositories of interest to you will be prefixed with ns-3. Official releases of ns-3 will be numbered as ns-3.release.hotfix. For example, a second hotfix to a still hypothetical release nine of ns-3 would be numbered as ns-3.9.2 on this page. The current development snapshot (unreleased) of ns-3 may be found at https://gitlab.com/nsnam/ns-3-dev/. The developers attempt to keep these repository in consistent, working states but they are in a development area with unreleased code present, so you may want to consider staying with an official release if you do not need newly-introduced features. You can find the latest version of the code either by inspection of the repository list or by going to the Getting Started web page and looking for the latest release identifier. To download the most recent release (assuming it is ns-3.30 in this case), type the following into your shell (remember you can substitute the name of your chosen release number, or omit specifying it to download the tip of ns-3-dev) apt install g++ python3 python3-dev pkg-config sqlite3 cmake 6 After download process completes, you should have several new directories under ~/repos/ns-3-allinone: apt install g++ python3 python3-dev pkg-config sqlite3 cmake 7 Go ahead and change into ns-3.30 under your ~/repos/ns-3-allinone directory. You should see something like the following there: apt install g++ python3 python3-dev pkg-config sqlite3 cmake 8 You are now ready to build the ns-3 distribution. Downloading ns-3 Using a TarballThe process for downloading ns-3 via tarball is simpler than the Mercurial process since all of the pieces are pre-packaged for you. You just have to pick a release, download it and decompress it. As mentioned above, one practice is to create a directory called repos in one's home directory under which one can keep local Mercurial repositories. One could also keep a tarballs directory. If you adopt the tarballs directory approach, you can get a copy of a release by typing the following into your Linux shell (substitute the appropriate version numbers, of course): apt install g++ python3 python3-dev pkg-config sqlite3 cmake 9 If you change into the directory ns-allinone-3.30 you should see a number of files: apt install python3-setuptools git 0 You are now ready to build the ns-3 distribution. Building ns-3 with build.pyThe first time you build the ns-3 project you should build using the allinone environment. This will get the project configured for you in the most commonly useful way. Change into the directory you created in the download section above. If you downloaded using Mercurial you should have a directory called ns-3-allinone under your ~/repos directory. If you downloaded using a tarball you should have a directory called something like ns-allinone-3.13 under your ~/tarballs directory. Type the following: apt install python3-setuptools git 1 You will see lots of typical compiler output messages displayed as the build script builds the various pieces you downloaded. Eventually you should see the following magic words: apt install python3-setuptools git 2 Once the project has built you typically will not use ns-3-allinone scripts. You will now interact directly with Waf and we do it in the ns-3-dev directory and not in the ns-3-allinone directory. Configuration with WafTo see valid configure options, type ./waf --help. The most important option is -d <debug level>. Valid debug levels (which are listed in waf --help) are: "debug" or "optimized". It is also possible to change the flags used for compilation with (e.g.): apt install python3-setuptools git 3 or, alternately, the gcc compiler apt install python3-setuptools git 4 Note: Unlike some other build tools, to change the build target, the option must be supplied during the configure stage rather than the build stage (i.e., "./waf -d optimized" will not work; instead, do apt install python3-setuptools git 5 The resulting binaries are placed in build/<debuglevel>/srcpath. For example, in a debug build you can find the executable for the first.cc example as build/examples/first. You can debug the executable directly by: apt install python3-setuptools git 6 Of course, you can run gdb in emacs, or use your favorite debugger such as ddd or insight just as easily. In an optimized build you can find the executable for the first.cc example as build/examples/ns-<version>-first-optimized. In order to forcibly disable python bindings, you can provide the following option: apt install python3-setuptools git 7 In order to tell the build system to use the sudo program to set the suid bit if required, you can provide the following option: apt install python3-setuptools git 8 To start over a configuration from scratch, type: apt install python3-setuptools git 9 Or if you get stuck and all else fails: apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools 0 followed by changing back into ns-3-allinone and doing: apt install python3-setuptools git 1 will basically reset your build state. To see all waf options: apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools 2 Validatingns-3 has unit tests that can be run to verify the installation: apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools 3 which should produce output like: apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools 4 Using PythonSee this page. TroubleshootingSee this page. Obsolete informationOlder versions of ns-3, prior to 3.15, supported using cygwin to run on Windows platform. WindowsThere are three basic options for Windows support:
An alternative Windows platform is MinGW. There are maintainers who attempt to keep a subset of ns-3 running on MinGW, but it is not "officially" suppported. This means that bugs filed against MinGW will be addressed as time permits. Cygwin can sometimes be problematic due to the way it actually does its emulation, and sometimes interactions with other Windows software can cause problems. If you do use Cygwin or MinGW; and use Logitech products, we will save you quite a bit of heartburn right off the bat and encourage you to take a look at the MinGW FAQ. Search for "Logitech" and read the FAQ entry, "why does make often crash creating a sh.exe.stackdump file when I try to compile my source code." Believe it or not, the ``Logitech Process Monitor`` insinuates itself into every DLL in the system when it is running. It can cause your Cygwin or MinGW DLLs to die in mysterious ways and often prevents debuggers from running. Beware of Logitech software when using Cygwin. |
