Zynthian development environment setup

One of my new years goals is to contribute something to Zynthian development :sweat_smile:

Currently I have 2 options on my mind:

  1. Remote debugging via VS Code on “bare metal” installation on RPi4
    It should work on any OS, so it is the first way that I’ve thought of.
  2. Dockerized Zynthian image (I doubt that it already exist)
    This is very tricky, as it would require to run some audio server that may enable audio routing from Docker image to OS of the host. And I even don’t know if e.g. Pulse Audio client may be wired up to existing Zynthian configuration.

I’ve seen Zynthian Emulator Setup for Development - ZynthianWiki and Zynthian Emulator - ZynthianWiki but if I’m not wrong it works only on Linux hosts and unfortunately my daily OS is Windows 10. So some viable alternative would be ideal.

Could you recommend some other development environment setup for my use-case?

1 Like

Hi @multim!

Years ago, i used to develop for zynthian on my linux desktop using the “emulator”, but as the project got more complex, it becames more difficult to keep working a reliable development environment on desktop and i ended developing directly on RBPi.

The true is that there are too many dependencies with the “real machine” and you always need to test changes on a real zynthian, so i realized it’s better to improve my development workflow having a “real zynthian” aside my desktop computer.

My setup is really simple:

  • A working zynthian machine connected to my local network
  • My linux desktop computer connected to my local network

I work with a local copy of the repositories on my desktop and make the changes with my favorite text editor (Kate), copy the files to the zynthian machine (grsync is really useful here) and test the changes on the zynthian machine (the terminal is my best friend here).
When new code is tested, i commit the changes and test the “update process” to close the loop.

This is my workflow, but other developers probably have their own way.

Anyway, if you really want to work on a “desktop development environment”, you are very welcome. Feel free to work on it and please, share your advances.

Best regards!


Maybe take a look at systemd-nspawn with binfmt


Oh, didn’t see the bit about windows 10. Install VirtualBox and run a vm.

Or use wsl.

Running Zynthian on VirtualBox is something I may consider.

And I really doubt that on WSL I can get any working audio routing, also zyntian emulator most probably will crash there.

I also use a real Zynthian, or at least a Raspberry Pi for most development. Contrary to @jofemodo I tend to work on the files on the actual RPi via ssh, e.g. using vi or via VNC running Code::Blocks IDE. I test then commit and push to GitHub directly on the RPi. I use a Windows 10 laptop with built-in SSH command line client and Edge browser to access Zynthian’s noVNC. I sometimes use a Bodhi Linux netbook instead of the Windows 10 laptop. I tried using VSCode with its SSH plugin but that kills the RPi due to horrible memory usage (and leakage) in its C++ plugin.

1 Like

You wont be able to run Zynthian on Virtualbox as Virtualbox is a hypervisor, not a cpu emulator. You could run Ubuntu or Fedora on Virtualbox and use those to emulate arm code though.

The most confusing lscpu output I’ve seen in a long time.

This is the Zynthian webconfig from the 2021-09-25 image running in a systemd-nspawn container. Set up with the instructions above on Fedora. systemd isn’t a thing so you have to hand start a bunch of stuff after setting some environment variables.

Also, you don’t get a soundcard…

I’ve done the remote vscode debugging properly

Debugging python code on zynthian from a computer with remote vscode


I’ve just added this…


Not quite finished as I have to get something to eat. . .


Thanks, very nice tutorial. Finally I’ve got some time to invest in zynthian contribution.

I did steps for webconf and succesfully catched desired breakpoint, but when I did similar steps for zynthian-ui it failed.
I assume that some preconditions have to be satisfied to run/debug but which are essential and in what order?
I’ve found zynthian.sh launcher script, but I’m not sure which steps are mandatory to debug GUI?
Just running load_config_env() should be enough?
Or when I run systemctl stop zynthian it turned off some more required services?

To debug zynthian-ui you need X running. I do it thus:

systemctl stop zynthian
X :0 -r -s0

Within VSCode:

  • Install Python plugin
  • Connect to remote host (zynthian) via ssh
  • Start debugging

I use this VSCode launc.json:

    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
            "name": "Zynthian",
            "type": "python",
            "request": "launch",
            "program": "zynthian_main.py",
            "console": "integratedTerminal",
            "justMyCode": true,
            "subProcess": true,
            "env": {
                "DISPLAY": ":0"
            "name": "Zynthian Debug",
            "type": "python",
            "request": "launch",
            "program": "zynthian_main.py",
            "console": "integratedTerminal",
            "justMyCode": true,
            "env": {
                "DISPLAY": ":0",
                "ZYNTHIAN_LOG_LEVEL": "10"

I mostly use VNC to access the GUI to allow this to be all done from the comfort of my sofa…

  • Within webconf INTERFACE->UI Options: Enable VNC Server
  • Reboot (The service does not necessarily start fully straight away so this tends to be a good step)
  • Access GUI via http://zynthian.local:6080/vnc.html?autoconnect=true&password=raspberry

If you have changed the hostname or your LAN exposes it differently (e.g. DNS gives it a local domain name) then adjust zynthian.local.
If you have changed the password, adjust raspberry.
Of course you can just access it without this but have to enter the password each time which I find boring.

[Edit] Note about the X options:
:0 tells it to use display 0 which is configured by default as the main display. (:1 is the VNC desktop view - you could put it there if it is beneficial, e.g. you want to see the Zynthian GUI and plugin GUIs within the same view.)
-r tells it to disable key repeat which can cause issues with computer keyboard control (that I use a lot in VNC).
-s0 tells it to disable screensaver to avoid the display (including VNC) blanking after a period of inactivity.


I used arguments -s 0 with whitespace and run X.
But after starting dubug in vscode it failed in zynthian_gui_info.py:44

Exception AttributeError
module 'zyngui.zynthian_gui_config' has no attribute 'top'

I use latest stable (updated via webconf).

This is an indication that it is not able to run the GUI - almost certainly because it does not find the X server. Have you set the env vars in VSCode’s launch.json?

Thanks again, I missed that option. Now it’s working.

It was also already helpful to find down this little bug:

OK, so It seems fix was easier than I thought (or at least I think so).

So what are the next steps to include this PR in (review) backlog. Is linking PR enough and target branch (testing) correct?

Yes. I will review it.

My setup is as follows, just in case anyone finds it useful:

  • I mount the RPi folder on my machine (a Linux host) using sshfs
mkdir remote-zynthian
sshfs root@zynthian.local:/zynthian/ remote-zynthian
  • With any editor (VSCode in my case), I edit files as if they were local
code remote-zynthian
  • I run Xnest on my host (with a proper geometry)
Xnest -s 0 -geometry 1280x720+0+0 :5
  • Open a terminal and set the DISPLAY environment variable to the Xnest screen, and then connect to the RPi using SSH with X forwarding
export DISPLAY=:5
ssh root@zynthian.local -X
  • Then, run the zynthian_main.py, which will open inside the Xnest