Installation

This page explains how to install gr-satellites on Linux, macOS and Windows. It covers the three methods the project supports (the Ubuntu PPA, conda, and building from source), the distribution packages maintained by others, the Python dependencies, the optional extras, and how to check that the installation works.

Choosing an Installation Method

Method	Platforms	Best for
Ubuntu PPA	Ubuntu 20.10 and later	The easiest route on Ubuntu.
conda	Linux, macOS, Windows	Windows and macOS users, and Linux distributions without a suitable GNU Radio package.
From source	Linux (and possibly macOS)	Developers, testers of the `main` branch, and anyone who wants the latest code.

Distribution packages maintained outside the project also exist: Arch Linux (AUR, gr-satellites-git), Debian (testing and unstable) and MacPorts.

Requirements

gr-satellites is a GNU Radio out-of-tree module, so it needs GNU Radio itself. The GNU Radio version decides which branch or release series you need:

GNU Radio	gr-satellites series	Branch	Status
3.10	`v5.x.y`	`main` (development), `maint-3.10` (releases)	Current
3.9	`v4.x.y`	`maint-3.9`	Frozen on 2025-07-31
3.8	`v3.x.y`	`maint-3.8`	Frozen on 2025-07-31
3.8	`v2.x.y`	`maint-3.8-v2`	No longer changed
3.7	`v1.x.y`	`maint-3.7`	No longer changed

The main branch's CMakeLists.txt requires GNU Radio 3.10 (find_package(Gnuradio "3.10" ...), with the analog, blocks, digital, fft and filter components), CMake 3.8 or newer, and pybind11.

Python packages used at runtime:

Package	Used for
`construct` (2.9 or later)	All telemetry parsers.
`requests`	Telemetry submission to the FUNcube, PW-Sat2 and BME servers.
`websocket-client`	Submission to the BME WebSocket server.
PyYAML (`yaml`)	Loading SatYAML files. It is normally present as a GNU Radio dependency.
NumPy	Several blocks and the utilities. It is a GNU Radio dependency.

Optional extras:

Extra	Needed for
`feh` image viewer	Showing images in real time while they are received (see Files and Images).
`gr-tnc_nx` (from the `beesat-sdr` project)	Only for the `--use_tnc_nx` option of the Mobitex deframer. A built-in Mobitex deframer is used by default.
Matplotlib	The `smog_p_spectrum` utility and the `tools/waveform_plot.py` script.
The `ssdv` program (fork with JY1SAT support)	The `gr_satellites_ssdv` utility.

Ubuntu PPA

The PPA provides the latest version for Ubuntu 20.10 and later:

sudo add-apt-repository ppa:daniestevez/gr-satellites
sudo apt-get update
sudo apt-get install gr-satellites

The Debian packaging in the repository declares gnuradio, python3-construct, python3-requests and python3-websocket as dependencies and recommends feh, so these come along with the package.

conda

conda installs GNU Radio and gr-satellites into a virtual environment that does not interfere with the rest of the system. This is the recommended method on Windows.

Install Miniconda (or any conda distribution) as a regular user.
Optionally stop the base environment from activating in every shell:
```
conda config --set auto_activate_base false
```
Activate the environment you want to use:
```
conda activate base
```
Install GNU Radio:
```
conda install -c conda-forge gnuradio
```

Install gr-satellites into the same environment:

conda install -c conda-forge gnuradio-satellites

The conda package is named gnuradio-satellites, not gr-satellites. The gr_satellites command and the GNU Radio Companion blocks are available whenever that environment is active. Run conda deactivate to leave it.

Building from Source

1. Install the build dependencies

Some build dependencies of out-of-tree modules are not needed to run GNU Radio, so distributions may not install them with GNU Radio. On Debian-based systems check for:

Package	Why
`liborc-0.4-dev`	Required by GNU Radio's CMake configuration.
`libsndfile1-dev`	Needed with GNU Radio 3.9 and later.
`libspdlog-dev`	Needed with GNU Radio 3.10 and later.
pybind11 development files	The Python bindings. `CMakeLists.txt` calls `find_package(pybind11 REQUIRED)`.
`cmake`, `pkg-config`, `gnuradio-dev`, `python3-dev`	The build itself (all listed in the repository's `debian/control`).

Then install the Python packages, either from your distribution or with pip:

pip3 install --user --upgrade construct requests websocket-client

2. Get the source

Download the latest release, or clone the repository to work on main:

git clone --recursive https://github.com/daniestevez/gr-satellites

--recursive also downloads the satellite-recordings submodule with sample recordings (see Sample Recordings).

3. Build and install

cd gr-satellites
mkdir build
cd build
cmake ..
make
sudo make install
sudo ldconfig

Two CMake options are available: ENABLE_DOXYGEN (on by default only when Doxygen is found) and ENABLE_MANPAGES. Run the unit tests after make with:

make test

4. Make sure Python can find the module

If Python cannot locate the installed module, any use of gr-satellites fails with:

ModuleNotFoundError: No module named 'satellites'

The module is often installed under a path such as /usr/local/lib/python3/dist-packages/satellites. Point PYTHONPATH at the parent directory:

export PYTHONPATH=/usr/local/lib/python3/dist-packages/

Add this line to ~/.bashrc or ~/.bash_profile to make it permanent for terminal sessions. If you start GNU Radio Companion from the desktop rather than from a shell, set the variable in your session startup files (for example xprofile) instead.

Verifying the Installation

Print the version:

gr_satellites --version

The output starts with a line such as:

gr_satellites v5.10.0-git

followed by the copyright and GPL-3.0-or-later license notice. List the supported satellites:

gr_satellites --list_satellites

This prints one entry per SatYAML file, sorted by name, with each transmitter's frequency, modulation and framing, similar to:

Satellites supported by gr_satellites v5.10.0-git:
* 1KUNS-PF (NORAD 43466)
    1k2 FSK downlink 437.300 MHz FSK AX100 ASM+Golay
    9k6 FSK downlink 437.300 MHz FSK AX100 ASM+Golay
...

Note: --version and --list_satellites are the only options that work without a satellite, and then they must be the first argument. Any other first argument that starts with - (including --help) makes gr_satellites print the short usage line and exit with status 1, because a satellite must come first. See Basic Usage.

In GNU Radio Companion, the blocks appear under the Satellites category (for example Satellites > Core > Satellite decoder).

Sample Recordings

The satellite-recordings/ directory of the repository is a git submodule with short recordings of many satellites. They are real (single channel) 48 kHz WAV files. In an existing clone, fetch them with:

git submodule update --init

If you installed from a package, clone the satellite-recordings repository directly. The test.sh script at the root of the repository runs gr_satellites on many of these recordings and doubles as a list of working examples.

Performance Note: VOLK Profile

On some systems the AO-73 decoder and similar decoders fail if volk_profile has never been run. The cause appears to be the Viterbi kernel VOLK picks when there is no ~/.volk/volk_config file. If these decoders give no output:

Run volk_profile.
If that does not help, look in ~/.volk/volk_config for a line containing volk_8u_x4_conv_k7_r2_8u avx2 avx2 and replace both avx2 with spiral or generic.

Troubleshooting Installation

Symptom	Cause	Fix
`ModuleNotFoundError: No module named 'satellites'`	Python does not search the install prefix.	Set `PYTHONPATH` as described above.
`ModuleNotFoundError: No module named 'construct'` (or `requests`, `websocket`)	Missing Python dependency.	Install it with pip or your package manager.
CMake cannot find GNU Radio 3.10	Wrong branch for your GNU Radio version, or missing `gnuradio-dev`.	Use the branch from the table above, or install the development package.
CMake errors about ORC, sndfile or spdlog	Missing build-only dependencies.	Install `liborc-0.4-dev`, `libsndfile1-dev`, `libspdlog-dev`.
Blocks missing in GNU Radio Companion	GRC started without the right `PYTHONPATH`, or a different conda environment.	Start GRC from a shell where `gr_satellites` works.

See the Troubleshooting page for runtime problems, and the changelog for what changed between releases.