Build UHD from Source on Linux, macOS, and Windows

Building UHD from source gives you full control over the version, enabled components, and install prefix. The build system uses CMake and follows the same configure-build-install pattern on all platforms. This guide covers dependency setup, cloning the repository, configuring CMake with common options, and running the build.

Prerequisites

Compiler Requirements

The following compilers are officially supported:

Compiler	Minimum Version
GCC	7.3.0
Clang	6.0.0
MSVC (Visual Studio)	16.0 (VS 2019)

The free Community edition of Visual Studio is sufficient. During installation, select the Desktop Development with C++ workload.

Dependency List

Ubuntu / Debian
Fedora
macOS
Windows

Install all build dependencies with a single command:

sudo apt-get install autoconf automake build-essential ccache cmake cpufrequtils \
    doxygen ethtool g++ git inetutils-tools libboost-all-dev libncurses5 \
    libncurses5-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev python3-dev \
    python3-mako python3-numpy python3-requests python3-scipy \
    python3-setuptools python3-ruamel.yaml

Your exact package list may differ depending on your Ubuntu/Debian version.

sudo dnf -y install boost-devel libusb1-devel doxygen python3-docutils \
    python3-mako python3-numpy python3-requests python3-ruamel-yaml \
    python3-setuptools cmake make gcc gcc-c++

On older Fedora releases use yum in place of dnf. Your exact package list may differ.

Install Xcode from the App Store, then install the Command Line Tools:

xcode-select --install

Use MacPorts (recommended) or HomeBrew to install Boost, Python, and Mako. Many UHD developers find it easiest to first do sudo port install uhd to pull in all dependencies, then sudo port uninstall uhd before building from source.

Install all dependencies through the same package manager to avoid hard-to-diagnose runtime issues.

Dependencies are installed via downloadable EXE packages or a package manager such as vcpkg or Conan.Required packages and download links:

Package	Min Version	Notes
CMake	3.12	cmake.org — add `bin` to `%PATH%`
Boost	1.76 (Windows)	boost.org — match architecture and MSVC toolset
LibUSB	1.0	github.com/libusb/libusb — path must not contain spaces
Python	3.7	python.org — add to `%PATH%`, match architecture

After installing Python, install the required Python packages:

pip3 install requests numpy ruamel.yaml setuptools mako poetry

Key dependency version minimums (all platforms):

Package	Minimum Version	Required?
CMake	3.12	Required
Boost	1.71 (1.76 on Windows)	Required
Python	3.7	Required
Mako	0.4.2	Required
NumPy	1.11	Required for Python API
Pybind11	2.7	Build-time (Python API only)
LibUSB	1.0	Optional (USB devices)
Doxygen	1.8	Optional (API docs)

Pybind11 is bundled with the UHD source tree. If no system-installed Pybind11 is found, the in-tree version is used automatically. Using the system version is recommended when building alongside GNU Radio or other software that also uses Pybind11.

Get the Source Code

The UHD source is hosted on GitHub:

git clone https://github.com/EttusResearch/uhd.git

Branch Overview

Branch	Purpose
`master`	Main development branch — new features and bug fixes
`UHD-*`	Stable release branches (e.g., `UHD-4.7`) — bugfixes only
`UHD-*.LTS`	Long-term support branches — extended bugfix lifetime

All versioned releases are tagged. You can browse source archives for release tags on GitHub.

For production deployments, prefer a tagged release or a stable UHD-* branch over master.

Build Instructions

cd <uhd-repo-path>/host
mkdir build
cd build
cmake ../
make
make test          # optional — runs the test suite
sudo make install

CMake Configuration Options

Pass options to CMake with -D<OPTION>=<VALUE>. The most commonly used options are listed below.

Install Prefix

cmake -DCMAKE_INSTALL_PREFIX=/opt/uhd ../

Common Feature Flags

CMake Option	Default	Description
`ENABLE_PYTHON_API`	ON (Linux/macOS), OFF (Windows)	Build the UHD Python C extension
`ENABLE_LIBUHD`	ON	Build the core UHD shared library
`ENABLE_C_API`	ON	Build the C language API wrapper
`ENABLE_EXAMPLES`	ON	Build example programs
`ENABLE_TESTS`	ON	Build the unit test suite
`ENABLE_STATIC_LIBS`	OFF	Build a static `libuhd.a` instead of shared
`ENABLE_DPDK`	OFF	Enable DPDK transport support
`ENABLE_RFNOC_DEV`	OFF	Install RFNoC/HDL development files
`NEON_SIMD_ENABLE`	ON	Enable NEON SIMD on ARM; disable when cross-compiling

Python API Options

When ENABLE_PYTHON_API=ON, verify CMake is using the correct Python installation:

cmake -DENABLE_PYTHON_API=ON \
      -DPYTHON_EXECUTABLE=/usr/bin/python3 \
      -DPYTHON_INCLUDE_DIR=/usr/include/python3.x \
      ../

All three PYTHON_* variables (PYTHON_EXECUTABLE, PYTHON_INCLUDE_DIR, PYTHON_LIBRARY) must point to the same Python installation. Mixing installations causes runtime errors in the Python module.

Build Python Utilities Only (no full UHD build)

If you only need rfnoc_image_builder (e.g., in a CI environment for building FPGA bitfiles):

cmake -DENABLE_LIBUHD=OFF \
      -DENABLE_PYMOD_UTILS=ON \
      -DUHD_BOOST_REQUIRED=OFF \
      -DENABLE_DOXYGEN=OFF \
      -DENABLE_MAN_PAGES=OFF \
      -DENABLE_MANUAL=OFF \
      ../

This configuration completes in under a minute with a minimal install footprint.

Static Library Build

cmake -DENABLE_STATIC_LIBS=ON <path-to-uhd-source>

When linking the static library, you must ensure the entire archive is loaded so that global device registration objects are initialised at startup:

g++ your_app.cpp \
    -Wl,-whole-archive <path-to-uhd-libs>/libuhd.a \
    -Wl,-no-whole-archive \
    -ldl -lpthread -l<all other libraries>

Post-Install Setup

Update the shared library cache (Linux)

Make sure libuhd.so is discoverable at runtime:

sudo ldconfig

Alternatively, add the library directory to /etc/ld.so.conf before running ldconfig.

Add UHD to PATH (Windows)

Add C:\Program Files\UHD\bin (or your custom prefix \bin) to the %PATH% environment variable.

Download FPGA images

Fetch the device firmware and FPGA images that match your installed UHD version:

uhd_images_downloader
# or use the full path:
/usr/local/lib/uhd/utils/uhd_images_downloader.py

On macOS with MacPorts, images are downloaded and installed automatically — no manual step required.

Platform-Specific Notes

Ubuntu 20.04 CMake path issue

On Ubuntu 20.04, CMake may follow the /bin → /usr/bin symlink and miscalculate include paths, producing errors like:

CMake Error in python/CMakeLists.txt:
  Imported target "Boost::chrono" includes non-existent path "/include"

Fix by ensuring /usr/bin precedes /bin in PATH, or pass:

cmake -DCMAKE_FIND_ROOT_PATH=/usr ../

ARM cross-compilation

When cross-compiling for ARM targets that do not support NEON (e.g., Odroid XU4 via standard SDK), disable NEON extensions explicitly:

cmake -DNEON_SIMD_ENABLE=OFF ../

Windows LibUSB paths

CMake on Windows cannot use pkg-config, so set LibUSB paths manually in the CMake GUI (Advanced View):

LIBUSB_INCLUDE_DIRS (PATH) → directory containing libusb.h, e.g. C:\local\libusb-1.0.22\include\libusb-1.0
LIBUSB_LIBRARIES (FILEPATH) → full path to libusb-1.0.lib, e.g. C:\local\libusb-1.0.22\MS64\dll\libusb-1.0.lib

Building Applications Against UHD

If your application uses CMake, add the following to your CMakeLists.txt to locate the installed UHD headers and libraries:

find_package(UHD 4.7.0)
# Provides: UHD_INCLUDE_DIRS, UHD_LIBRARIES

See examples/init_usrp in the UHD source tree and the installed UHDConfig.cmake for a complete working example.

Alternative: PyBOMBS

PyBOMBS automates the source build process including dependency resolution on Linux and Unix-like systems:

pybombs install uhd

PyBOMBS can install UHD into system directories or a user’s home directory, removing the requirement for root access.

Introduction

Installation

USRP Devices

Prerequisites

Compiler Requirements

Dependency List

Get the Source Code

Branch Overview

Build Instructions

CMake Configuration Options

Install Prefix

Common Feature Flags

Python API Options

Build Python Utilities Only (no full UHD build)

Static Library Build

Post-Install Setup

Platform-Specific Notes

Ubuntu 20.04 CMake path issue

ARM cross-compilation

Windows LibUSB paths

Building Applications Against UHD

Alternative: PyBOMBS

Build docs developers (and LLMs) love

Introduction

Installation

USRP Devices

Documentation Index

​Prerequisites

​Compiler Requirements

​Dependency List

​Get the Source Code

​Branch Overview

​Build Instructions

​CMake Configuration Options

​Install Prefix

​Common Feature Flags

​Python API Options

​Build Python Utilities Only (no full UHD build)

​Static Library Build

​Post-Install Setup

​Platform-Specific Notes

​Ubuntu 20.04 CMake path issue

​ARM cross-compilation

​Windows LibUSB paths

​Building Applications Against UHD

​Alternative: PyBOMBS

Build docs developers (and LLMs) love

Prerequisites

Compiler Requirements

Dependency List

Get the Source Code

Branch Overview

Build Instructions

CMake Configuration Options

Install Prefix

Common Feature Flags

Python API Options

Build Python Utilities Only (no full UHD build)

Static Library Build

Post-Install Setup

Platform-Specific Notes

Ubuntu 20.04 CMake path issue

ARM cross-compilation

Windows LibUSB paths

Building Applications Against UHD

Alternative: PyBOMBS