Installing Reticulum: Difference between revisions

Latest revision as of 15:49, 11 September 2026

How to get Reticulum onto the machines people actually have.

Out of the box: you probably do not need this page

If you want to use the network from a laptop or phone, install an app that bundles Reticulum and configures it for you:

App	Runs on	Get it
MeshChatX	Windows, macOS, Linux, Android	meshchatx.com
Sideband	Android, Windows, macOS, Linux	GitHub releases
Retichat or Columba	iPhone	App Store, GitHub

Connecting to ScotMesh walks you through MeshChatX step by step, and Choosing a client compares them. Come back here when you want Reticulum on a server or a Raspberry Pi, want Nomad Network or the command-line tools, or want to see what is going on underneath.

Full installation

Reticulum is a Python program. On every platform the install is pip install rns, with one wrinkle per platform.

Linux

On Ubuntu 24.04, Debian 12 and other recent distributions, a system-wide pip install is refused with error: externally-managed-environment. That is deliberate on the distribution's part (PEP 668), not a fault. Use a virtual environment:

sudo apt install python3-venv
python3 -m venv ~/reticulum
~/reticulum/bin/pip install rns

The commands are then ~/reticulum/bin/rnsd, ~/reticulum/bin/rnstatus and so on. To have them on your path, add export PATH=~/reticulum/bin:$PATH to ~/.bashrc.

pipx install rns also works, if you have pipx, and puts the commands on your path for you.

On a Raspberry Pi the same applies. A Pi Zero 2 or later is plenty.

macOS

Install Python 3 from python.org or with Homebrew (brew install python), then:

pip3 install rns

If pip refuses for the same PEP 668 reason, use a virtual environment exactly as for Linux.

Windows

Install Python 3 from python.org, ticking Add Python to PATH in the installer. Then in a terminal:

pip install rns

The config file lands in C:\Users\<you>\.reticulum\config.

Android

Use one of the apps above; both Android apps bundle Reticulum. Running it by hand under Termux is possible but fiddly and gains you nothing for ordinary use.

First run

Run rnsd once. It creates ~/.reticulum/config and stops when you press Ctrl+C. Then add an interface to ScotMesh as described in Connecting to ScotMesh, start it again, and check with rnstatus.

Keeping it running

Reticulum only works while rnsd is running. On Linux, run it as a systemd service so it starts at boot; the unit file is in Connecting to ScotMesh. On macOS and Windows, leave the terminal open, or use MeshChatX, which keeps its own Reticulum running while the app is open.

Checking it works

rnstatus

Each interface should show Status: Up and traffic that rises over the first minute or two. Troubleshooting explains the output line by line and what to do when it is not Up.

Updating

pip install --upgrade rns

(with the same path prefix if you used a virtual environment), then restart rnsd. Reticulum releases are backwards compatible on the wire, so you do not have to update in step with anyone else.

@@ Line 1: / Line 1: @@
-''Outline — the shape of the page, not the page. Expand or replace freely.''
+How to get Reticulum onto the machines people actually have.
-Getting <code>rns</code> onto the machines people actually have. Short and command-heavy.
+== Out of the box: you probably do not need this page ==
-== To cover ==
+If you want to use the network from a laptop or phone, install an app that bundles Reticulum and configures it for you:
-* <code>pip install rns</code>, and where the config lands
+{| class="wikitable"
-* Linux, macOS, Windows, Android via Termux
+! App !! Runs on !! Get it
-* Running <code>rnsd</code> as a service so it survives a reboot
+|-
-* Checking it works: <code>rnstatus</code> and how to read it
+| '''MeshChatX''' || Windows, macOS, Linux, Android || [https://meshchatx.com meshchatx.com]
-* The venv question on Ubuntu 24.04 — PEP 668 blocks a system-wide pip install
+|-
+| '''Sideband''' || Android, Windows, macOS, Linux || [https://github.com/markqvist/Sideband/releases GitHub releases]
+|-
+| '''Retichat''' or '''Columba''' || iPhone || [https://apps.apple.com/us/app/retichat/id6762225314 App Store], [https://github.com/torlando-tech/Columba-iOS GitHub]
+|}
+[[Connecting to ScotMesh]] walks you through MeshChatX step by step, and [[Choosing a client]] compares them. Come back here when you want Reticulum on a server or a Raspberry Pi, want Nomad Network or the command-line tools, or want to see what is going on underneath.
+== Full installation ==
+Reticulum is a Python program. On every platform the install is <code>pip install rns</code>, with one wrinkle per platform.
+=== Linux ===
+On Ubuntu 24.04, Debian 12 and other recent distributions, a system-wide <code>pip install</code> is refused with <code>error: externally-managed-environment</code>. That is deliberate on the distribution's part (PEP 668), not a fault. Use a virtual environment:
+<syntaxhighlight lang="text">sudo apt install python3-venv
+python3 -m venv ~/reticulum
+~/reticulum/bin/pip install rns</syntaxhighlight>
+The commands are then <code>~/reticulum/bin/rnsd</code>, <code>~/reticulum/bin/rnstatus</code> and so on. To have them on your path, add <code>export PATH=~/reticulum/bin:$PATH</code> to <code>~/.bashrc</code>.
+<code>pipx install rns</code> also works, if you have pipx, and puts the commands on your path for you.
+On a Raspberry Pi the same applies. A Pi Zero 2 or later is plenty.
+=== macOS ===
+Install Python 3 from [https://www.python.org python.org] or with Homebrew (<code>brew install python</code>), then:
+<syntaxhighlight lang="text">pip3 install rns</syntaxhighlight>
+If pip refuses for the same PEP 668 reason, use a virtual environment exactly as for Linux.
+=== Windows ===
+Install Python 3 from [https://www.python.org python.org], ticking '''Add Python to PATH''' in the installer. Then in a terminal:
+<syntaxhighlight lang="text">pip install rns</syntaxhighlight>
+The config file lands in <code>C:\Users\&lt;you&gt;\.reticulum\config</code>.
+=== Android ===
+Use one of the apps above; both Android apps bundle Reticulum. Running it by hand under Termux is possible but fiddly and gains you nothing for ordinary use.
+=== First run ===
+Run <code>rnsd</code> once. It creates <code>~/.reticulum/config</code> and stops when you press Ctrl+C. Then add an interface to ScotMesh as described in [[Connecting to ScotMesh#Full installation: Reticulum yourself|Connecting to ScotMesh]], start it again, and check with <code>rnstatus</code>.
+=== Keeping it running ===
+Reticulum only works while <code>rnsd</code> is running. On Linux, run it as a systemd service so it starts at boot; the unit file is in [[Connecting to ScotMesh#Keeping it running|Connecting to ScotMesh]]. On macOS and Windows, leave the terminal open, or use MeshChatX, which keeps its own Reticulum running while the app is open.
+=== Checking it works ===
+<syntaxhighlight lang="text">rnstatus</syntaxhighlight>
+Each interface should show '''Status: Up''' and traffic that rises over the first minute or two. [[Troubleshooting]] explains the output line by line and what to do when it is not Up.
+=== Updating ===
+<syntaxhighlight lang="text">pip install --upgrade rns</syntaxhighlight>
+(with the same path prefix if you used a virtual environment), then restart <code>rnsd</code>. Reticulum releases are backwards compatible on the wire, so you do not have to update in step with anyone else.
 [[Category:Getting Started]]