Beginners Headless Zynthian Tutorial

Hi Everyone,
Here’s my notes for beginners to easily install a headless Zynthian :

Download last stable Zynthian OS image

Download etcher and burn the image on an SD card (class 10)

Connect an ethernet cable between the raspberry pi and your computer (or the two on an ethernet switch)

Put the SD on the raspberry, power on and wait a little bit

Install chrome on your computer and:

If you aren’t on an ethernet switch connected on internet, configure the wifi on the WebConf:

System / WIFI / Add Network
Mode = ON

In the WebConf, update Zynthian OS:

Software / Update
System / Reboot

In the WebConf, setup the hardware:

Hardware / Kit / Custom
Hardware / Audio / Select your soundcard on the list
Hardware / Display / Generic HDMI Display
Hardware / Wiring / DUMMIES
System / Reboot

Install VNC server on the raspberry pi

sudo apt update
sudo apt install realvnc-vnc-server 

Option 1 : via the WebConf terminal (System / Terminal)
Option 2 : via SSH:

  • On MacOS, open the osx terminal and type :
    ssh zynthian.local

(first ask your mac password then zynthian password = raspberry)

Note : On MacOS, if you need to re-burn your SD card and have the error message “Host key verification failed” when you try to connect via SSH, you need to erase the previous SSH information with the nano text editor in the ssh known_hosts by running this command :
sudo nano /var/root/.ssh/known_hosts
In nano, delete the zynthian line (control K), then write the file (control O + enter), then quit (control X).

Activate VNC server on the raspberry pi

sudo raspi-config
Interfacing Options / VNC / Yes

Download VNC viewer in your computer

Connect to the Zynthian UI via VNC:

Type the raspberry pi IP address (on Windows) or zynthian.local (on MacOS) in VNC Viewer.
User name : root
Password : raspberry

Configure Zynthian UI for headless use in the WebConf:

Interface / UI options
Advanced view : ON
Enable Touch Widgets: ON
Enable cursor: ON

1 Like


If you want to see the native GUI, for example of Pure data, you need to install an X11 server on your computer:

On the X11 server’s terminal (xterm), type:

ssh -Y root@zynthian.local

On the Zythian UI, create a new Pure Data layer or other engine with supported native GUI:

The Pure Data GUI should appears on your computer screen.

If you want to graphically access to the Zynthian OS files architecture (not recommended for beginners), you need to install an SFPT client on your computer:

Open an SFPT connection:

Server : zynthian.local (MacOS) or IP Address (Windows)
User : root
Password : raspberry

If you want to access to the Pure Data externals folders (for exemple for manually installing externals that aren’t available via another way), go to :


And upload your custom externals if you want.

1 Like

Additional notes : There’s some strange things concerning pure data :
When you open the native GUI, there’s a dialogue windows that ask for creating a Pd folder in the root directory. So in a normal Zynthian use, I think that this windows is always open. I don’t know if it’s a problem. In fact, there’s a Pd directory in root…
I also don’t know why, but the ableton link external is not as the same folder as the others : /usr/local/lib/pd-externals

And if you want to access to the Zynthian UI via your smartphone or tablet:

Connect your devices on the same network

Alternatively, on stage, disconnect the Zynthian from internet, configure it as a hotspot and connect your device to it. For this, go to the WebConf:

System / WIFI / Hotspot

Install VNC viewer for iOS and Android:

Hi @gnuv!

Would you like to add your tutorial to the wiki?
In such a case i would create a wiki account for you …



Yes, of course :wink:

That’s it :


Great Work mate! You are recruited for the Wiki’s Team
Thanks a lot!