This tutorial is aimed at Mac OS X and Debian-based Linux distributions. It should work with other Linux distros too. Sorry, I don't have a Windows machine.
Before you start, make sure to install a full Bitcoin node first and set at least the following minimum options in
Use random string generator for
rpcpassword. The longer, the better.
If you already have bitcoin node installed, you need to reindex the blockchain:
When running Bitcoin-Qt it should be enough to just close and reopen the wallet. It will reindex the chain automatically.
#1 Install LevelDB
A database engine is required to store transaction information. I use leveldb only because I haven't had luck installing RocksDB.
On Mac OS X
Install leveldb using homebrew:
brew install leveldb
If you have a Debian-based Linux distribution you can use the following command:
sudo apt-get install python3-leveldb libleveldb-dev
If you don't, then you'll have to figure it out. I haven't had luck installing from source.
#2 Install Python 3.7
ElectrumX developer decided to use newer Python 3 which isn't installed on many operating systems by default.
Let's install it manually.
on Mac OS X
Install the latest version of Python 3 with homebrew:
brew install python3
on Linux distributions
There are many different options to install Python 3.7 based on your Linux distribution.
Ubuntu (option 1)
Install the latest python 3.7 on Ubuntu:
sudo apt-get update && sudo apt-get install python3.7 python3.7-dev python3-pip
Other Debian-based distro (option 2)
Some Debian-based distributions may already be shipped with the latest Python.
sudo apt-get install python3.7 python3.7-dev python3-pip
In a case of an error try using the following option instead.
From a source (option 3)
If you can't install it from a repository, just compile it from the source code. It should work for most distros.
tar xvf Python-3.7.0.tgz
sudo make altinstall
Please note that the compilation will take "forever".
However, if your CPU has more than 4 cores, you can speed it up a bit by using
make -j8 instead.
Install required Python packages
You will also need to install some Python 3.7 dependencies for ElectrumX.
Let's first upgrade setuptools:
python3.7 -m pip install --upgrade pip setuptools wheel
then install some required packages:
python3.7 -m pip install --upgrade aiohttp pylru leveldb plyvel aiorpcx ecdsa
If the above command gives you an error, try installing it with
sudo (try to avoid it as much as possible, though).
#3 Install and set up ElectrumX
Clone the ElectrumX code from a GitHub repository using git:
git clone https://github.com/FreedomNode/electrumx-no-shitcoins.git
Run the installation script (use
sudo if it doesn't work):
python3.7 setup.py install
Next, create a data folder where the blockchain data will be stored:
Synchronizing with a Bitcoin node takes anywhere between 1-5 days depending on your hardware.
If you want to speed up the process a bit, download one of these data files and put it in the
#4 Create a self-signed certificate
To allow Electrum wallets to connect to your server over SSL you need to create a self-signed certificate.
Go to the data folder:
and generate your key:
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr
Follow the on-screen information. It will ask for certificate details such as your country and password. You can leave those fields empty.
When done, create a certificate:
openssl x509 -req -days 1825 -in server.csr -signkey server.key -out server.crt
These commands will create 2 files:
When configuring the ElectrumX instance, make sure to add server.key to
SSL_KEYFILE and server.crt to
SSL_CERTFILE. More on this in the next step.
#5 Launch ElectrumX as service
First, make sure a fully validating Bitcoin node is running:
It should output information about your node such as block height, open connections etc.
If it doesn't, run the node first.
on OS X
OS X lacks Systemd to manage system services, so we will use UNIX's default svscan instead.
Create a service folder that will hold symlinks to ElectrumX scripts.
Copy daemontools scripts from the GitHub repo to your home directory:
mkdir -p ~/scripts/electrumx
cp -R ~/source/electrumx/contrib/daemontools/ ~/scripts/electrumx
Set up ENV variables within
~/scripts/electrumx/env folder. Each variable is located in a separate file.
When finished open the log/run file:
and edit the log path. In my case it is
/Users/bitcoin/ElectrumX/logs, yours may be different.
Save the file by pressing ESC and typing
:wqa followed by ENTER.
Change the permissions for the file so it can be executed:
chmod +x ~/scripts/electrumx/log/run
Also, change the permission for another file that executes the server:
chmod +x ~/scripts/electrumx/run
svscan process to monitor electrumx services:
svscan ~/service & disown
Add services to the folder:
ln -s ~/scripts/electrumx electrumx
They should be immediately recognized by
Check the last few lines of the log to see whether the service outputs any errors:
tail -F ~/.electrumx/logs/current | tai64nlocal
If it does, check your configuration again. Errors are pretty self-explanatory but if you're stuck, let me know in the comments section.
ElectrumX is very resource intensive when it comes to open files so it needs a higher limit:
ulimit -n 10000
Check that it worked:
ulimit -a | grep 'open files'
Make sure the limit is set after every restart:
echo "ulimit -n 10000" >> ~/.bash_profile
If the above method doesn't work, try the following:
sudo launchctl limit maxfiles 10000 unlimited
Restart the service for new changes to take effect.
Stop the service:
svc -d ~/service/electrumx
Always wait for the service to be terminated properly by checking with logs.
Start the service again:
svc -u ~/service/electrumx
Above commands will only execute when svscan is already initialized. You can check the service's status with:
Most if not all Debian-based distribution use Systemd by default. Make sure that is the case for your system:
sudo stat /proc/1/exe | grep systemd
If it outputs something like
File: '/proc/1/exe' -> '/lib/systemd/systemd' you're good to go.
Open a sudo session and copy a service file from the ElectrumX repo to your Systemd directory:
cp ~/source/electrumx/contrib/systemd/electrumx.service /lib/systemd/system/
Edit the file to match your setup:
Press i and start editing.
You need to edit at least
When you're happy with the changes, hit ESC and type
:wqa followed by ENTER.
Create a configuration file for the server:
and configure it according to your environment.
Start the service:
systemctl start electrumx
and check the output:
journalctl -u bitcoin -f
If it gives you no errors, enable the service:
systemctl enable electrumx
You can exit the sudo session now:
#6 Set up a Banner file
Say hi to connecting Electrum wallets (via Electrum console) using a banner file.
It may contain any information such as your server version, donation address, contacts and even info on other services you offer. It's purely up to you.
The content of my banner.txt file looks like this:
Welcome to satoshi.onthewifi.com, a Taiwanese Bitcoin Electrum node sponsored by freedomnode.com!
Donation address: $DONATION_ADDRESS
Bitcoin Core $DAEMON_VERSION
If you would like to support this server you can donate by clicking
Help -> Donate to server
in your Electrum Client or use $DONATION_ADDRESS directly.
and is located in the data folder
You can save it to any location and let ElectrumX know via
BANNER_FILE variable in either
env/ folder or
/etc/electrumx.conf depending on your operating system.
Don't forget to restart the server after changing any server's settings.
#7 Accept incoming connections
If you want to help the network and let others connect to your server, you have to open specific TCP ports.
For a default Electrum set up, those ports are 50001 and 50002.
On Linux, this can be easily done via iptables:
sudo iptables -A INPUT -p tcp --dport 50001 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 50002 -j ACCEPT
However, Mac OS X users will need to install some kind of firewall. The built-in one only manages outgoing connections.
Also, don't forget to open ports on your router if applicable. There are too many routers to cover them in this tutorial. Sorry.
To test the connection, open your Electrum wallet. Start it with an argument
--oneserver for extra privacy.
On Mac OS X the command is:
open -a /Applications/Electrum.app --args --oneserver
Click a green/red dot in the bottom right corner. A server configuration will pop up.
Unclick "Select server automatically" and type in your server's local/remote IP address or a hostname. Click "Use SSL" and confirm.
If you did everything right, your wallet should start synchronizing the chain data immediately. It shouldn't take more than 10 seconds to finish.
Congratulations! You no longer rely on "trusted" 3rd parties. You also made yourself protected from contentious hard forks and coin splits.
Please let me know in the comments section below if you have any questions or suggestions.
My big thank you goes to Mashuri Clark that gave me some useful tips and corrected some steps for the OS X part.
P.S. Feel free to use our UASF BIP148 Electrum server: bitcoin.freedomnode.com:50001