Chapter 2. Setup and Build Instructions
Prev | Part I. Wireshark Build Environment | Next

## Chapter 2. Setup and Build Instructions

## 2.1. UN*X

### 2.1.1. Build environment setup

The following must be installed in order to build Wireshark:

- A C compiler and a C++ compiler;
- The Flex lexical analyzer;
- Python 3;
- CMake;
- Several required libraries.

Either make or Ninja can be used to build Wireshark; at least one of those must be installed.

To build the manual pages, Developer’s Guide and User’s Guide, Asciidoctor, Xsltproc, and DocBook must be installed.

Perl is required to generate some code and run some code analysis checks.

Some features of Wireshark require additional libraries to be installed. The processes for doing so on various UN*X families is shown here.

There are shell scripts in the `tools` directory to install the packages and libraries required to build Wireshark. Usage is available with the `--help` option. `root` permission is required to run the scripts. The available scripts and their options for a given family of UN*Xes are shown in the section for that family.

#### Alpine Linux

The setup script is `tools/alpine-setup.sh`; its options are:

- `--install-optional` install optional software as well
- `--install-all` install everything
- `[other]` other options are passed as-is to apk

#### Arch Linux and pacman-based systems

The setup script is `tools/arch-setup.sh`; its options are:

- `--install-optional` install optional software as well
- `--install-test-deps` install packages required to run all tests
- `--install-all` install everything
- `[other]` other options are passed as-is to pacman

#### BSD systems such as FreeBSD, NetBSD, OpenBSD, and DragonFly BSD

The setup script is `tools/bsd-setup.sh`; its options are:

- `--install-optional` install optional software as well
- `[other]` other options are passed as-is to pkg manager

#### Debian, and Linux distributions based on Debian, such as Ubuntu

The setup script is `tools/debian-setup.sh`; its options are:

- `--install-optional` install optional software as well
- `--install-deb-deps` install packages required to build the .deb file
- `--install-test-deps` install packages required to run all tests
- `--install-qt5-deps` force installation of packages required to use Qt5 (not recommended)
- `--install-qt6-deps` force installation of packages required to use Qt6
- `--install-all` install everything
- `[other]` other options are passed as-is to apt

#### RPM-based Linux distributions such as Red Hat, Centos, Fedora, and openSUSE

The setup script is `tools/rpm-setup.sh`; its options are:

- `--install-optional` install optional software as well
- `--install-rpm-deps` install packages required to build the .rpm file
- `--install-qt5-deps` force installation of packages required to use Qt5 (not recommended)
- `--install-qt6-deps` force installation of packages required to use Qt6
- `--install-all` install everything
- `[other]` other options are passed as-is to the packet manager

#### macOS

You must first install Xcode.

As with Windows we provide pre-built third party libraries which will be automatically installed if you set the WIRESHARK_BASE_DIR CMake variable to a directory that is writable by you, such as wireshark-third-party at the same level as your Wireshark source code directory. You can alternatively use two scripts to install the packages and libraries required to build Wireshark and its documentation: `tools/macos-setup-brew.sh`, which will use the Homebrew package manager and `tools/macos-setup.sh`, which will build any required libraries and tools locally, except for Qt 6.

`tools/macos-setup-brew.sh` supports the following options:

- `--install-required` install third party libraries required to build Wireshark
- `--install-optional` install optional third party libraries
- `--install-dmg-deps` install packages required to build the .dmg file
- `--install-sparkle-deps` install the Sparkle automatic updater
- `--install-all` install everything
- `--install-stratoshark` install libraries required to build Stratoshark and the Falco Events plugin
- `[other]` other options are passed as-is to brew

`tools/macos-setup.sh` supports the following options:

- `-n` dry run; don’t build or install any packages
- `-p` specify the installation prefix; /usr/local is the default
- `-t` specify the minimum macOS target version
- `-u` uninstall packages

We recommend `tools/macos-setup-brew.sh` if you’re using Homebrew and you don’t need to worry about backward compatibility with older macOS releases.

If you will be building Wireshark with Qt 6, which is the default for Wireshark 4.0 and later, you will also have to install Qt; the `tools/macos-setup.sh` script will not install Qt 6. To install Qt, go to the Download Qt for open source use page, select “macOS” if it’s not already selected, and then select “Qt online installer for macOS“. This will download a .dmg for the installer; launch the installer. It will require that you log into your Qt account; if you don’t have an account, select “Sign up“ to create one. The next page will require you to accept the LGPL (Lesser GNU Public License); do so. Continue to the “Installation Folder“ page of the installer screen, and select the “Custom installation“ option. On the “Select Components“ screen of the installer, select, for the desired Qt version, the “macOS” component. For example, at the time of this writing the Qt 6.8.3 “macOS” component is used to build the official packages. The “Qt Debug Information Files” component contains dSYM files which can be used for debugging. You can deselect all of the other the components such as “Qt Charts” or “Android xxxx” as they aren’t required.

Qt 6 needs the "Qt 5 Compatibility Module" to be installed as well. Additionally, the module "Qt Multimedia" may be installed, to support advanced controls for playing back streams in the RTP Player dialog.

### 2.1.2. Building

Before building:

On macOS, you will need to set the Qt installation directory in the environment:

    WIRESHARK_QT6_PREFIX_PATH=~/Qt/6.8.3/macos
    export WIRESHARK_QT6_PREFIX_PATH

If you want to append a custom string to the package version, run the command

    WIRESHARK_VERSION_EXTRA=-YourExtraVersionInfo
    export WIRESHARK_VERSION_EXTRA

The recommended (and fastest) way to build Wireshark is with CMake and Ninja. Building with make took nearly 2x time as Ninja in one experiment.

CMake builds are best done in a separate build directory, such as a `build` subdirectory of the top-level source directory. If that directory is a subdirectory of the top-level source directory, to generate the build files, change to the build directory and enter the following command:

    cmake ..

to use make as the build tool or

    cmake -G Ninja ..

to use Ninja as the build tool.

If you created the build directory in the same directory that contains the top-level Wireshark source directory, to generate the build files, change to the build directory and enter the following command:

    cmake ../{source directory}

to use make as the build tool or

    cmake -G Ninja ../{source directory}

to use Ninja as the build tool. `{source directory}` is the name of the top-level Wireshark source directory.

If you need to build with a non-standard configuration, you can run

    cmake -LH ../{source directory}

to see what options you have.

You can then run Ninja or make to build Wireshark.

    ninja
    # or
    make

Once you have build Wireshark with `ninja` or `make` above, you should be able to test it by entering `run/wireshark`.

### 2.1.3. Optional: Install

Install Wireshark in its final destination:

    make install

Once you have installed Wireshark with `make install` above, you should be able to run it by entering `wireshark`.

### 2.1.4. Optional: Create User’s and Developer’s Guide

To build the Wireshark User’s Guide and the Wireshark Developer’s Guide, build the `all_guides` target, e.g. `make all_guides` or `ninja all_guides`. Detailed information to build these guides can be found in the file doc/README.documentation.adoc in the Wireshark sources.

### 2.1.5. Optional: Create an installable or source code package

You can create packages using the following build targets and commands:

Source code tarball
  Build the `dist` target.
deb (Debian) package
  Create a symlink named debian in the top-level source directory to packaging/debian, then run `dpkg-buildpackage`.
RPM package
  Build the `wireshark_rpm` target.
AppImage package
  Build the `wireshark_appimage` target.
macOS .dmg package containing an application bundle
  Build the `wireshark_dmg` or `stratoshark_dmg` targets.

Installable packages typically require building Wireshark first.

### 2.1.6. Troubleshooting during the build and install on Unix

A number of errors can occur during the build and installation process. Some hints on solving these are provided here.

If the `cmake` stage fails you will need to find out why. You can check the file `CMakeOutput.log` and `CMakeError.log` in the build directory to find out what failed. The last few lines of this file should help in determining the problem.

The standard problems are that you do not have a required development package on your system or that the development package isn’t new enough. Note that installing a library package isn’t enough. You need to install its development package as well.

If you cannot determine what the problems are, send an email to the wireshark-dev mailing list explaining your problem. Include the output from `cmake` and anything else you think is relevant such as a trace of the `make` stage.

Prev | Up | Next
1.7. Reporting problems and getting help | Home | 2.2. Windows