Skip to main content

QRL Node Installation

Installing QRL is simple, and is possible on most modern operating systems. The install relies on python3.5 or newer and the pip3 python package install system.

Minimum Node Hardware Requirements

There are some basic requirements that must be met to run a QRL node. See the QRL Node Requirements documentation for more info.

Follow the directions below to get started running a QRL Node.

Node Installation

QRL Ubuntu Installation

Installation instructions for the QRL Node on Ubuntu.

Tested in the latest LTS version Ubuntu 20.04

# Update && Upgrade Software Packages
sudo apt update && sudo apt upgrade -y

# Install the required packages for QRL
sudo apt-get -y install swig3.0 python3-dev python3-pip build-essential pkg-config libssl-dev libffi-dev libhwloc-dev libboost-dev cmake libleveldb-dev

# Install latest setuptools
pip3 install -U setuptools

# Install latest service identity package
pip3 install service-identity==21.1.0

# Install QRL
pip3 install -U qrl

This is the recommended installation method, and most common way to run a QRL Node. Even functions in Windows subsystem for Linux.

Running QRL

After successful installation of the node the QRL command line tools are available. For more information see the QRL Node CLI Documentation.

The node software runs in the foreground of the current shell, to run the node in the background, use something like screen to disconnect the shell from the running node allowing syncing to happen in the background.


To begin the syncing process run the node software.


Output looks something like this.

2021-09-25 18:22:28,045|2.1.2 python|unsynced|MainThread | INFO : grpc public service - started !
2021-09-25 18:22:28,046|2.1.2 python|unsynced|MainThread | INFO : [TWISTED] P2PFactory starting on 19000
2021-09-25 18:22:28,047|2.1.2 python|unsynced|MainThread | INFO : QRL blockchain ledger 2.1.2 python
2021-09-25 18:22:29,049|2.1.2 python|synced |MainThread | INFO : Status changed to ESyncState.synced

This will start the node software in the foreground of the current shell, create a default node directory at ~/.qrl and begin syncing blocks from the known peers via the p2p network.

start_qrl Help

The start_qrl command has additional advanced configuration that can be passed via the command line. Below is an explanation of each additional option.

usage: start_qrl [-h] [--mining_thread_count MINING_THREAD_COUNT] [--quiet]
[--qrldir QRL_DIR] [--no-colors]
[--network-type {mainnet,testnet}]
[--miningAddress MINING_ADDRESS]
[--mockGetMeasurement MEASUREMENT] [--debug] [--mocknet]

QRL node

optional arguments:
-h, --help show this help message and exit
--mining_thread_count MINING_THREAD_COUNT, -m MINING_THREAD_COUNT Number of threads for mining
--quiet, -q Avoid writing data to the console
--qrldir QRL_DIR, -d QRL_DIR Use a different directory for node data/configuration
--no-colors Disables color output
--network-type {mainnet,testnet} Runs QRL Testnet Node
--miningAddress MINING_ADDRESS QRL Wallet address on which mining reward has to be credited.
--mockGetMeasurement MEASUREMENT Warning: Only for integration test, to mock get_measurement
--debug Enables fault handler
--mocknet Enables default mocknet settings
--mining_thread_count -m MINING_THREAD_COUNTNumber of CPU threads to use for mining
--quiet -qQuiet the output to the console
--qrldir -d QRL_DIRDirectory to use for root node data (default ~/.qrl
--no-colorsDisable colored output to console
--loglevel -lDEBUG,INFO,WARNING,ERROR,CRITICAL} Set the logging level
--network-type {mainnet,testnet}Set the type of node to run setting default node directory to ~/.qrl-testnet

Screen Session

Run the QRL node in a background screen terminal to allow the node to run after user disconnects from the shell. For more information on Screen, read the manual here

Install screen if not already installed.

sudo apt install screen

Start the node in a detached screen session named QRL:

screen -dm start_qrl -S QRL

Reattach to the screen shell:

screen -r qrl-node

Disconnect from the shell using the ctl + a then d key sequence described here in the screen docs.

Systemd Service

Enable the QRL node to start at boot and restart using the systemd utility that ships with most Linux systems.

Create the new qrl.service file in the /etc/systemd/system/ directory. This will require sudo privileges to write into the directory.

sudo touch /etc/systemd/system/qrl.service

Now modify that file to contain the following, edit for your local user and settings.

### save this into /etc/systemd/system/qrl.service
## enable with sudo systemctl enable qrl.service
## start with sudo systemctl start qrl

Description=QRL Node

# Modify the following to suit your user
User=ubuntu # Local Username
WorkingDirectory=/home/ubuntu # Local users home directory
ExecStart=/home/ubuntu/.local/bin/start_qrl # Location of the start_qrl executable `which start_qrl`


Enable the script to start at boot an restart if failed:

sudo systemctl enable qrl.service

Now start the node service and begin syncing blocks from the network.

sudo systemctl start qrl.service

Check the status of the node with

sudo systemctl status qrl.service

Crontab Script

To start the node upon reboot, use a script and crontab to enable a fault tolerant node.


Recommended to enable a system service for a more robust monitored node operation.

Create the script below somewhere on your system.

nano ~/

Add the following content to the file, save and exit.

## Start QRL node ##
# Requires modification to function on local system
# Must point to absolute directory for start_qrl
# Typically found at /home/$USER/.local/bin/start_qrl
# locate with `which start_qrl`

screen -Sdm QRL /home/fr1t2/.local/bin/start_qrl

Change the permissions to allow the script to be executed

chmod +x ~/

Modify crontab to enable the script to start at every reboot.

crontab -e

Add the following to the end of the crontab configuration file, changing the user home directory to suite the local installation. Must be an absolute file path.

@reboot /home/$USER/

Now anytime the computer reboots the script will run, starting the node.

Check for Running Node

On a Linux system, depending on how the node was started you can see if it's running in a few ways.

QRL Node Log

By default the node will write a log to the home qrl directory ~/.qrl. The last action of the node is recorded and the log will be fairly constant as the node validates blocks.

To view this log, use the tail function that ships with most Linux systems.

tail -f ~/.qrl/qrl.log

This will stream any changes to the log file.

ps Process Status Command

Using the process status or ps command we can see what is running. Combine this with something like grep and we can narrow it down to only qrl processes

ps aux |grep qrl

If the node is running it will print the process and related information.

In a screen Session

If the node is running in a screen service following the guides above one can see what is running using the screen list command

screen -ls

Reattach using screen -r SCREEN_NAME

Systemd Service

Print the status of the running systemd service.

sudo service qrl.service status


sudo systemctl status qrl.service