CondaInstall

Why use conda?

Conda is a cross-platform package manager (supporting Linux, macOS, and Windows) that makes it easy to install GNU Radio, its dependencies, and out-of-tree modules in a self-contained environment. Conda lets you create independent environments with their own sets of packages, and those environments are separate from your system installation and other package managers. If you've struggled with installing GNU Radio by other methods, you want to use GNU Radio with other bleeding-edge software available through conda-forge, or you want to try out a new version without affecting your tried-and-true system installation, conda may be right for you! In addition to GNU Radio, there are also related software packages you can install that may be of interest.

conda-forge

The conda packages for GNU Radio are unofficial and supported through volunteer effort within the conda-forge community. Conda-forge is a community-maintained collection of conda packages where anyone with interest can help improve or add packages. Please report and discuss any packaging-specific issues with the maintainers at the gnuradio feedstock. If you'd like to help or are interested in adding other related software to conda-forge (e.g. out-of-tree modules), get in touch with the maintainers through Github.

Installation using radioconda (recommended)

Radioconda is a full conda distribution available at [1] that includes GNU Radio. You can follow the instructions there and then skip all of the installation instructions here. If you don't know much about conda and just want to get going, that's a good place to start. Otherwise, continue on.

Installation using conda

Step 1: Install conda itself

First, you will need to install a base conda distribution so that you can use the conda program to create an environment and install the GNU Radio packages. If you already have this and can run conda on a command line or use the Anaconda Navigator to install packages, skip to the next step.

If this is your first time using conda, we recommend miniforge for the base installation. This provides a minimal environment to run conda that is already set up to pull packages from conda-forge (which is where you can find GNU Radio). Download and install miniforge by following the instructions at [2]. Installers for many different platforms are available there, but the most relevant are the following:

• Linux x86_64
• macOS x86_64
• Windows x86_64

For Linux and macOS, run the downloaded installer from a console and follow the prompts:

• (Linux) bash Miniforge3-Linux-x86_64.sh
• (macOS) bash Miniforge3-MacOSX-x86_64.sh

By default, this will install miniforge to your home directory at ~/miniforge3 and allow you to use the conda command from any console.

For Windows, double click on the downloaded installer executable and follow the prompts. By default, this will install miniforge to your user directory at C:\Users\USERNAME\miniforge3 and add a "Miniforge Prompt" entry to your start menu. Running the "Miniforge Prompt" should bring up a console window where your base conda environment is activated and you can use the conda command.

This guide provides a nice introduction to using conda generally; it may help you better understand the rest of these instructions, but it is not necessary to read.

(Optional, recommended) It may be convenient to now install mamba in your base environment and use it in place of the conda command:

conda install mamba

Mamba is a third-party alternative to conda that is written in C instead of Python, and its main benefit is faster dependency resolution when installing packages. If you do install mamba, you can simply use the mamba command in place of conda for all subsequent steps.

Step 2: Create an environment for GNU Radio

It's almost never a good idea to install additional packages to your base conda environment because their dependencies may interfere with conda's own dependencies. We recommend creating an environment specifically for GNU Radio and related packages. From a console with the base conda environment activated, run

conda create -n gnuradio

to create an empty environment called "gnuradio". Enter the environment by activating it with the command:

conda activate gnuradio

Before installing the GNU Radio packages, we need to ensure that the environment is set up to look for packages from conda-forge:

conda config --env --add channels conda-forge
conda config --env --set channel_priority strict

Now you're ready to actually install GNU Radio!

Step 3: Install GNU Radio from conda-forge

GNU Radio on conda-forge is split into a few subpackages. Most users will be happy with the full installation provided by the gnuradio metapackage. From within your activated "gnuradio" environment (previous step), run the command:

conda install gnuradio

This will install the latest available version of GNU Radio along with the latest version of Python. If you want a specific version of the gnuradio package (get a list of possibilities from conda search gnuradio), you can specify it like

conda install gnuradio=3.8.2

If you want a specific version of Python, you can install it before gnuradio or specify them together like

conda install gnuradio python=3.8

To upgrade packages in your environment to their latest available versions, use the upgrade command

conda upgrade --all

The gnuradio metapackage installs all of the following subpackages:

• gnuradio-core
• gnuradio-grc
• gnuradio-iio
• gnuradio-qtgui
• gnuradio-soapy
• gnuradio-uhd
• gnuradio-video-sdl
• gnuradio-zeromq

If you don't want all of those and their dependencies, you can install the ones you'd like individually like

conda install gnuradio-uhd

to get only the core package (always a dependency) and UHD support without any GUI elements.

Using GNU Radio from conda

You can use GNU Radio from a conda environment in mostly the same way that it is normally used, provided that you have activated your "gnuradio" environment (or whatever name you might give it). So from a fresh console, you'll need to run

conda activate gnuradio

and then use whatever GNU Radio scripts or programs you want, for instance

gnuradio-companion

Windows users will find that GNU Radio Companion can also be launched from the Start Menu. Running it from there will first activate the appropriate environment, so all you need to do is click the icon!

GNU Radio will have access to the Python installed into the conda environment, and not any other installation. If you need specific Python packages to use with GNU Radio, just install them into the environment using conda install. As a last resort, pip or manual installation (python setup.py install) can also be used, but these will not be managed by conda and you'll have to be careful to manage your environment.

Installing related software

Beyond core GNU Radio and the in-tree modules, some out-of-tree modules and related software have also been packaged for conda. This is a non-exhaustive list of other packages that you can install using the conda install command:

• gnuradio-iridium
• gnuradio-osmosdr
• gnuradio-satellites
• gqrx
• limesuite
• rtl-sdr
• soapysdr-module-airspy
• soapysdr-module-airspyhf
• soapysdr-module-hackrf
• soapysdr-module-lms7
• soapysdr-module-plutosdr
• soapysdr-module-remote
• soapysdr-module-rtlsdr
• soapysdr-module-uhd
• uhd
• volk

If you have other hardware or OOT modules that you'd like to see supported, first search Anaconda Cloud to see if a package not listed above already exists on conda-forge or another channel. If it doesn't, you can create your own package recipe and submit it to conda-forge (see the documentation at [3] for details) and/or get in touch with the maintainers of the existing packages to see if they would be willing to help.

Building OOT modules to use with conda-installed GNU Radio

In the event that the OOT module you want to use is not packaged for conda, it is possible to build it from source and use it within your conda environment. You can follow the following instructions, or build a conda package for the OOT module following a recipe template. If you do either of these, please consider contributing your recipe/procedure so that others can benefit. See the note at the end of this section.

First, if you're doing this on Windows, you will need to have Visual Studio 2019 or newer installed. If you're not using VS2019 directly (e.g. VS2022), you will probably need to add its specific compiler version (MSVC v142) using the Visual Studio Installer by selecting the "MSVC v142 - VS 2019 C++ x64/x86 build tools" component under the list of "Individual Components".

Then, some special setup is required to ensure that the CMake packaging tool knows where to find dependencies and where to install the OOT module. Install the packaging tools we'll need to the conda environment that contains gnuradio-core by installing the purpose-built meta-package:

conda install gnuradio-build-deps

The gnuradio-build-deps metapackage ensures that you have all required build time dependencies installed and their versions are correct. This includes, the C/C++ compiler used to compile GNU Radio as well as CMake, Ninja, NumPy, pip, pkg-config, pybind11, etc.

Also make sure you have all of the OOT module's dependencies installed which might not be needed by GNU Radio itself.

Re-activate your environment if you just installed gnuradio-build-deps for the first time to set some environment variables:

(on Linux/macOS)

conda activate $CONDA_DEFAULT_ENV

(on Windows)

conda activate %CONDA_DEFAULT_ENV%

($CONDA_DEFAULT_ENV/%CONDA_DEFAULT_ENV is an environment variable that gives the name of the currently active conda environment. It does not mean to activate your base environment!)

Then run CMake like you normally would (e.g. from a build directory),

mkdir build
cd build

adding the following flags to your cmake command, so cmake .. becomes:

(on Linux/macOS)

cmake -G Ninja -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX -DCMAKE_PREFIX_PATH=$CONDA_PREFIX -DLIB_SUFFIX="" ..

(on Windows)

cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="%CONDA_PREFIX%\Library" -DCMAKE_PREFIX_PATH="%CONDA_PREFIX%\Library" -DGR_PYTHON_DIR="%CONDA_PREFIX%\Lib\site-packages" ..

It is possible that not all of these added arguments are necessary, and you might need more to help CMake locate particular libraries.

Once this cmake step succeeds, proceed with building the OOT as you would outside of the conda environment:

cmake --build .
cmake --build . --target install

Note: build errors due to PRIu64 being undefined have been observed in a couple of OOT modules when building within a conda environment. This happens because the environment is built with an older version of glibc that doesn't define that macro automatically. Until conda depends on at least glibc 2.18, the workaround is to add -D__STDC_FORMAT_MACROS to the build's CXXFLAGS. This can be done either by setting the CXXFLAGS environment variable or, if the OOT already defines CMAKE_CXX_FLAGS somewhere, adding it into the existing expression in the CMakeLists.txt file.

Document your results to help others: if you've succeeded in building an OOT in this way, please consider documenting your process in an issue filed at the radioconda GitHub! Helpful information to document includes the names of any extra conda packages that you needed to install as dependencies, and the exact CMake and build commands that you used.

Extra credit: if you're successful and want to be extra helpful, you're halfway to creating a conda recipe! Consider following the conda-build documentation to finish the job in creating a recipe and then submit it to conda-forge so others can benefit. You can use this template or existing recipes (like gnuradio-satellites) as an example.

Adding conda support directly to an OOT module

A template conda recipe for GNU Radio out-of-tree modules is now a part of gr_modtool. Beyond making it easier for anyone to bundle an OOT into a conda package, it is also straightforward to add the ability to build packages automatically through Github!

For any new OOT modules created with gr_modtool, you can find the conda recipe and configuration in the .conda directory. For existing modules, you can run gr_modtool newmod OOT_NAME to create a "new" module and copy the .conda directory into the existing module. Once you have a .conda directory created from the template, you can follow the additional instructions found in the README in that .conda directory for how to modify the recipe, build the package, and add continuous integration.

Installing pre-release versions

Sometimes, pre-release versions of GNU Radio will also be available through conda-forge (on a best effort basis!). So these don't get installed over release versions, they are provided on a separate channel label. For a release candidate ("RC" pre-release), that channel is conda-forge/label/gnuradio_rc. You can install from a special channel by using the -c flag with conda install, as in

conda install -c conda-forge/label/gnuradio_rc gnuradio

Since extra packages are unlikely to also be available and compatible with a pre-release version, we recommend creating a separate environment first and installing the pre-release there. So for example,

conda create -n grtest -c conda-forge/label/gnuradio_rc -c conda-forge gnuradio
conda activate grtest

Building GNU Radio from source within a conda environment

Take note that this is an advanced topic that is likely to be of interest to developers only. It is possible to install all of GNU Radio's dependencies into a conda environment and then build GNU Radio from source. This can be useful for development, where the source is being updated and rebuilds are frequent.

Create a development environment

Create and activate a development environment called "grdev":

conda create -n grdev
conda activate grdev
conda config --env --add channels conda-forge
conda config --env --set channel_priority strict

Install all of the dependencies (or a subset of them if you like):

(Linux)

conda install alsa-lib boost-cpp click click-plugins cmake codec2 cppzmq cxx-compiler fftw gtk3 gmp gsl libad9361-iio libcblas libiio libsndfile lxml mako ninja numpy pkg-config portaudio pybind11 pybind11-abi pygobject pyqt python pyyaml pyzmq qt qwt sdl soapysdr spdlog uhd volk zeromq libice-cos6-x86_64 libselinux-cos6-x86_64 libsm-cos6-x86_64 libx11-cos6-x86_64 libxau-cos6-x86_64 libxcb-cos6-x86_64 libxdamage-cos6-x86_64 libxext-cos6-x86_64 libxfixes-cos6-x86_64 libxrender-cos6-x86_64 libxxf86vm-cos6-x86_64 libuuid-cos6-x86_64 mesa-dri-drivers-cos6-x86_64 mesa-libgl-devel-cos6-x86_64 libudev-devel-cos6-x86_64 packaging

(macOS)

conda install boost-cpp click click-plugins cmake codec2 cppzmq cxx-compiler fftw gtk3 gmp gsl libad9361-iio libcblas libiio libsndfile log4cpp lxml mako ninja numpy pkg-config pybind11 pybind11-abi pygobject pyqt python pyyaml qt qwt sdl soapysdr spdlog uhd volk zeromq packaging

(Windows)

conda install boost-cpp click click-plugins cmake codec2 cppzmq cxx-compiler fftw gtk3 gsl libad9361-iio libcblas libiio libsndfile log4cpp lxml mako mpir ninja numpy pkg-config pybind11 pybind11-abi pygobject pyqt python pyyaml qt qwt sdl soapysdr spdlog uhd volk zeromq packaging

On Linux only, remove a symlink to the system udev that will get in the way of the linker:

rm $CONDA_PREFIX/lib/libudev.so.0

Pass necessary arguments to CMake

With the development environment activated and from a build directory within the source directory, call cmake with the following arguments:

(Linux)

cmake -G "Ninja" -DCMAKE_PREFIX_PATH=$CONDA_PREFIX -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX -DLIB_SUFFIX="" ..

(macOS)

cmake -G "Ninja" -DCMAKE_PREFIX_PATH=$CONDA_PREFIX -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX -DLIB_SUFFIX="" ..

(Windows)

cmake -G "Ninja" -DCMAKE_INSTALL_PREFIX="%CONDA_PREFIX%\Library" -DCMAKE_PREFIX_PATH="%CONDA_PREFIX%\Library" -DPYTHON_EXECUTABLE="%CONDA_PREFIX%\python" -DGR_PYTHON_DIR="%CONDA_PREFIX%\Lib\site-packages" ..

In time, hopefully this list of argument can be trimmed down to only specifying the prefix.

Build as normal

Proceed with building and installing as normal:

cmake --build .
cmake --build . --target install

Test build

To test that built binaries work correctly:

ninja test

FAQ

When I try to run GNU Radio, why do I get a ModuleNotFoundError (no module named ...)?

It is likely that you have another GNU Radio or Python installation interfering with your conda environment. See ModuleNotFoundError for more information on this problem in general. Verify that your Python path points to the correct directory by running

python -c "import sys; print('\n'.join(sys.path))"

and inspecting the output. If other directories come before your conda environment Python directory, you may have to modify your PYTHONPATH environment variable. If your conda environment Python directory does not appear at all, make sure that your PATH environment variable is set correctly to run the python executable from your conda environment and not some other installation of Python.

Why do I get cryptic error messages with a new GNU Radio installation (or new major version)?

There are a few flavors of this, but if you've just installed a new major version of GNU Radio (e.g. 3.8, 3.9), it's possible that some files from an old installation are conflicting with the new version. It can be helpful to ensure that all remnants of the older version have been purged from your system, especially if you've just installed the conda package and have previously used another package or installed from source. In particular, it can be helpful to clear the GNU Radio user preferences directory and start fresh. You can find the location of this directory by running

gnuradio-config-info --userprefsdir

Delete that directory or all of its contents, and you might have better luck starting GNU Radio without errors.

Why can't GNU Radio find my hardware device?

Provided you've installed the appropriate package for your hardware through conda (e.g. uhd) and the accompanying GNU Radio blocks (e.g. gnuradio-uhd), it's likely that you still need to follow extra steps to get your hardware running. Consult the documentation for your device and follow the additional steps it recommends beyond installing the basic software. For example:

• For Ettus UHD-supported devices, you'll need to download the images package into the conda environment by running the uhd_images_downloader script provided by uhd.
• Using Windows with a USB-connected device, you will probably need to install a USB driver for the device. Search for driver installation instructions for your device and follow those instructions. You will likely have to download and run Zadig to install the latest WinUSB driver for your device.

Whatever you need to do, make sure your device is visible and usable outside of GNU Radio before trying to track down any GR-specific problem.

Windows users: Interference from PothosSDR

If you get errors that include "ImportError: DLL load failed", or GNU Radio Companion is missing blocks that should be there, then it is possible that another GNU Radio installation like PothosSDR is interfering with your conda environment. To verify that this is happening, you can run

gnuradio-config-info --prefix

and see if the returned path points to PothosSDR instead of your conda environment.

You may not have installed PothosSDR explicitly (some apps install it themselves), so double check to make sure. If you don't need PothosSDR anymore, then it is likely that you can solve these errors by uninstalling it.

The main way that PothosSDR interferes with other installations is by setting certain environment variables globally. If you want to try to keep PothosSDR while still using GNU Radio from a conda environment, then you will have to unset these variables. To do this whenever your conda environment is activated, run

conda env config vars set GR_PREFIX= GRC_BLOCKS_PATH= UHD_PKG_PATH= VOLK_PREFIX=

This should work if you run gnuradio-companion from the "radioconda Prompt", but will not have any effect if you run "GNU Radio Companion" from the Start Menu.

To remove the interfering environment variables from the Windows registry, run

set GR_PREFIX= & setx GR_PREFIX "" & REG delete HKCU\Environment /F /V GR_PREFIX
set GRC_BLOCKS_PATH= & setx GRC_BLOCKS_PATH "" & REG delete HKCU\Environment /F /V GRC_BLOCKS_PATH
set UHD_PKG_PATH= & setx UHD_PKG_PATH "" & REG delete HKCU\Environment /F /V UHD_PKG_PATH
set VOLK_PREFIX= & setx VOLK_PREFIX "" & REG delete HKCU\Environment /F /V VOLK_PREFIX

This should work in all cases.