Debugging python code on zynthian from a computer with remote vscode

Hi! After having a hard time getting to terms with the codebase for the gui I thought:

“Oh gosh darnit, I wish I could set some breakpoints and see what the heck this thing is doing in the background with all those variables and objects…”

So I got a’ diggin and surprisingly i found a way!

So first you gotta go through this guide to set it up in vscode:

and after that you connect to your zynthian with ssh and x-forwarding enabled.

ssh -Y root@zynthian.local

Then you stop the zynthian service, with systemctl

systemctl stop zynthian.service

now you go back into vscode and open to the (remote) folder /zynthian/zynthian-ui, then select the main gui app ( within that folder and go to the upper run menu, and click debug current file.

If python debugging does not show as an option you might to need to install plugins for it.
I’d also recommend setting some breakpoints to be able to control a bit how things show up.

This should make the main gui pop up on your desktop (via x11 forwarding), and there you go!

:nerd_face: @riban


Hmmm… This isn’t working for me. I must admit that I have not followed all the instructions to the letter because I already had VSCode working over ssh to the Zynthian. I believe my problem to be that x-forwarding is not happening. Obviously there needs to be an xserver running on my laptop and for the ssh client within vscode to know about that and hence how to forward the display. I am not sure that your instructions specifically deal with that bit.

I got it working. I editied launch.json so that it looked like this:

    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit:
    "version": "0.2.0",
    "configurations": [
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "env": {
                "DISPLAY": "localhost:10.0"

Can’t remember the random stabs in vscode until I found the file to edit. I did also install another x11 server but I think you just need to make sure one is installed but consequently found that there is some dependency - vscode won’t necessarily start the x11 server. There are some extra hurdles until this works.

Hmm, It didn’t require any setup other than creating the ssh connection with the flag

This ssh connection is done in other terminal window outside vscode btw

Logging in to Zynthian over ssh using MobaXterm seems to work as long as the above change is made to the configuration. That change expects a specific xserver display which happens to be the one that MobaXterm exposes. I did try logging in toe Zynthian from Windows command line ssh with -Y option but that didn’t work, even if I manually started Xming. I am not clear the exact steps required because most of the online write-ups seem to be written by people who are reiterating their empirical solutions rather than explaining the mechanisms that enable the workflow.

I have been able to debug Python this way (thanks @Pastitas) without the overhead that running the c++ plugin seemed to have. With the c++ plugin my Zynthian would die after a few hours and need a reboot - I think due to excessive memory consumption. Maybe this is resolved - I haven’t tested it recently. I have been able to debug the Python code without needing to reboot (although a gotcha is that you must place your breakpoints within functions, not at their definition lines which only break once at startup.)

I have also been able to use vscode for git version control. It isn’t quite as intuitive as I had hoped but I have been able to commit and push changes so will persevere despite the command line being so much more familiar to me.

Oh yeah, I’m a Linux user so I made some assumptions on the main tutorial.

Maybe this should be added to the wiki?

I would much prefer to be using GNU/Linux but the most useful machines are my work laptops which are Windows.

I have found launch.json in /zynthian/zynthian-ui/.vscode. This seems to inform vscode how to launch applications that match its criteria. I still haven’t figured out how to use another xserver or do so without first opening a separate ssh client which seems rather odd.

I’ve been using a raspberry pi4 as the host, and its’ … almost … working .

Just setup my dev environment like this, here are the steps I took:

  1. I’m on Windows, these steps are for Windows
  2. Install VcXsrv
  3. Run VcXsrv (shows up as XLaunch)
  4. Generate id_rsa ssh key if you haven’t (i.e. run ssh-keygen and hit Enter on every prompt, or read up)
  5. Install VSCode & Remote Development Extension Pack
  6. Not sure if this is necessary, but I also installed Remote X11 and Remote X11 (SSH)
  7. Got to Remote Explorer in VSCode and add Zynthian (ssh -Y root@zynthian.local)
  8. Choose /zynthian/zynthian-ui folder
  9. Stop zynthian service (systemctl stop zynthian.service)
  10. Install Python extension in VSCode
  11. Go to Run & Debug and create a .vscode/launch.json inside the zynthian-ui folder
  12. Create a Python configuration and add the following to the configuration:
"cwd": "${fileDirname}",
"env": {
    "DISPLAY": "localhost:10.0"
  1. Open and click the RUN AND DEBUG button in the tab on the left

Thx @Pastitas & @riban :heart:

1 Like

Ok. Some weird stuff going on with the current working directory.
I just added print("Hi. I'm here:", os.getcwd()) to the top of and got

Hi. I'm here: /

when debugging as well as a neat exception:

No such file or directory: './img/zynthian_gui_loading.gif'


Hi. I'm here: /home/pi/zynthian-ui

when running it normally.

I was hoping the "cwd": "${fileDirname}" in launch.json would fix this but it didn’t :confused:

Got it. You just have to use the RUN AND DEBUG button up there instead of the one above the file, otherwise it won’t use the launch configuration.