{"id":13596706,"url":"https://github.com/cascadium/wsl-windows-toolbar-launcher","last_synced_at":"2025-04-09T20:31:18.807Z","repository":{"id":37709449,"uuid":"243102382","full_name":"cascadium/wsl-windows-toolbar-launcher","owner":"cascadium","description":"Adds linux GUI application menu to a windows toolbar","archived":false,"fork":false,"pushed_at":"2024-01-11T17:27:49.000Z","size":2438,"stargazers_count":1194,"open_issues_count":4,"forks_count":51,"subscribers_count":35,"default_branch":"master","last_synced_at":"2024-03-14T17:14:28.842Z","etag":null,"topics":["free","toolbar","ubuntu","vcxsrv","windows","windows-toolbar","windows-toolbar-launcher","wsl","wsl-environment","wsl2","x410","xming"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cascadium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-25T21:05:27.000Z","updated_at":"2024-06-11T01:55:59.110Z","dependencies_parsed_at":"2024-06-11T01:55:57.678Z","dependency_job_id":"759afaf8-fb47-4d6f-8777-c8aa7e6d3c11","html_url":"https://github.com/cascadium/wsl-windows-toolbar-launcher","commit_stats":{"total_commits":56,"total_committers":9,"mean_commits":6.222222222222222,"dds":0.2142857142857143,"last_synced_commit":"1a4394ae454808a70f41922c22c824b1bdd22b51"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cascadium%2Fwsl-windows-toolbar-launcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cascadium%2Fwsl-windows-toolbar-launcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cascadium%2Fwsl-windows-toolbar-launcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cascadium%2Fwsl-windows-toolbar-launcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cascadium","download_url":"https://codeload.github.com/cascadium/wsl-windows-toolbar-launcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248107305,"owners_count":21048897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["free","toolbar","ubuntu","vcxsrv","windows","windows-toolbar","windows-toolbar-launcher","wsl","wsl-environment","wsl2","x410","xming"],"created_at":"2024-08-01T16:02:41.524Z","updated_at":"2025-04-09T20:31:17.457Z","avatar_url":"https://github.com/cascadium.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# WSL Windows Toolbar Launcher\n\n## For Windows 11 Users, you probably don't need / want this project\n\nUnfortunately (or fortunately depending on your opinion - keep reading...) this script is of questionable value in Windows 11 since they neutered the taskbar (generally). I did test when the windows 10 insiders build had full wslg support and everything worked fine, but the windows 11 taskbar is now unrecognizable from that build and there is currently no way to add the toolbar in the way which this project expects.\n\nHowever as of Windows 11, this script is not actually required. If you run [powertoys](https://github.com/microsoft/PowerToys), you can enable **Powertoys Run** and use alt+space. Your GUI apps from your WSL installs will have shortcuts there with your distribution name in brackets as you launch them and you won't need to go looking for them in the traditional tree-based structure. Thanks to the new Windows 11 WSLG support, it should \"just work\" without any display magic or third party X11 servers.\n\nNote you may wait for the Windows indexer to refresh after you install a new app, but it will get there eventually automatically.\n\n\n## For Windows 10 Users\n\nThis script will create a Windows toolbar launcher for an underlying WSL install which\ncan be used to fire up linux native applications directly from Windows via the standard\nWindows toolbar, like this:\n\n![Demo](https://github.com/cascadium/wsl-windows-toolbar-launcher/raw/master/assets/demo.gif)\n\nIt's particularly cool because WSL 2 is coming which is unlocking unprecedented performance\nand compatibility improvements, so this will literally bring the full suite of Linux GUI\napplications directly to Windows UI.\n\n## Prerequisites\n\nThe script expects to be run **within** the WSL execution environment with:\n\n* A complete WSL install ready with bash, python3 and python3-pip installed.\n* An **X11 Server** running on your **windows host** (e.g. X410, Xming etc). This server\n  must be *reachable* from your WSL env (test with something like `wsl.exe -- source ~/.bashrc ; xterm`).\n  If this fails, check your `DISPLAY` variable (more details in [troubleshooting](#troubleshooting)).\n* A freedesktop menu installed (e.g. gnome-menus or a full desktop environment).\n\nAnd optionally (but recommended):\n\n* An installation of cairosvg if works on your distro (`pip3 install cairosvg`). This will allow you to convert `.svg`\n  based icons.\n* Imagemagick installed (`sudo apt install imagemagick` / `dnf install imagemagick` etc). This will allow you to have\n  an additional opportunity to convert appropriate icon files if other methods fail.\n\n## Installing and Running\n\nTo install:\n\n    pip3 install wsl-windows-toolbar\n\nTo run:\n\n    wsl-windows-toolbar\n\nAfter installation, right click on your toolbar, go to\n`Toolbars -\u003e New toolbar...` and select\n`%USERPROFILE%\\.config\\wsl-windows-toolbar-launcher\\menus\\WSL` as the target folder (unless\nyou selected an alternative directory).\n\nNote there are many options available with `--help` if you'd prefer to use alternative locations.\n\n## Updating\n\nIf new software has been installed in the WSL environment, simply run the script again from the WSL environment to pick\nthe new GUIs up.\n\nNotable changes:\n\n* Change in 0.3: Command is now `wsl-windows-toolbar` without the trailing `.py`.\n\n## Advanced Usage / Options\n\n```\n$ python wsl-windows-toolbar.py  --help\nUsage: wsl_windows_toolbar.py [OPTIONS]\n\nOptions:\n  -i, --install-directory PATH    Install the launchers here [default:\n                                  /c/Users/$USER/.config/wsl-windows-toolbar-\n                                  launcher/metadata]\n  -m, --metadata-directory PATH   Install any metadata here [default:\n                                  /c/Users/$USER/.config/wsl-windows-toolbar-\n                                  launcher/metadata]\n  -d, --distribution TEXT         WSL Distro to generate shortcuts for\n                                  [default: $WSL_DISTRO_NAME]\n  -u, --user TEXT                 WSL Distro's user to launch programs as\n                                  [default: $USER]\n  -y, --confirm-yes               Assume the answer to all confirmation\n                                  prompts is 'yes'  [default: False]\n  -f, --menu-file FILENAME        The *.menu menu file to parse  [default:\n                                  /etc/xdg/menus/gnome-applications.menu]\n  -w, --wsl-executable TEXT       Path to the WSL executable relative to the\n                                  windows installation  [default:\n                                  C:\\Windows\\System32\\wsl.exe]\n  -n, --target-name TEXT          Name to give to the created installation\n                                  (will be displayed in toolbar menu)\n                                  [default: WSL]\n  -t, --preferred-theme TEXT      Preferred menu theme to use  [default:\n                                  Adwaita]\n  -T, --alternative-theme TEXT    Alternative menu themes to consider (pass\n                                  multiple times)  [default: Papirus,\n                                  Humanity, elementary-xfce]\n  -j, --jinja-template-batch FILENAME\n                                  Optional Jinja template to use instead of\n                                  the inbuilt default (advanced users only)\n  -J, --jinja-template-shell FILENAME\n                                  Optional Jinja template to use instead of\n                                  the inbuilt default (advanced users only)\n  -r, --rc-file FILENAME          Optional rc file to source prior to\n                                  launching the command instead of ~/.bashrc\n  -D, --launch-directory DIRECTORY\n                                  Optional default linux path to open\n                                  applications relative to (defaults to ~)\n  --help                          Show this message and exit.\n```\n\n### Advanced Launcher Behaviour\n\nThe launcher process is fairly broken down to separate responsibilities and allow customizations\nat several layers. It looks like this:\n\n    lnk -\u003e vbscript (sometimes) -\u003e bat -\u003e wsl bash -\u003e app\n\nThe `.lnk` is the shortcut with the icon etc. The vbscript exists only to launch the batch file\nwithout a terminal window appearing. The batch file bootstraps the wsl bash script using `wsl.exe`\nwhich in turn (finally) launches the app. It may seem convoluted but I have found this is the\neasiest way to break it down to allow flexibility and ease of maintenance at each layer.\n\nNote the vbscript is only called if `run_in_terminal` is set to false (as it tends to be for most\napplications). The templates which define the batch and bash files are used may be overridden\nby `-j` and `-J` respectively, though you shouldn't usually need to override this behaviour.\n\nThe default templates used are `wsl-windows-toolbar-template.bat.j2` and\n`wsl-windows-toolbar-template.sh.j2`. The following possible variables passed\nthrough from the script:\n\n* `distribution`: The distribution selected in the script\n* `user`: The user selected in the script\n* `command`: The individual command for each launcher entry in WSL environment (e.g. `xterm`)\n* `wsl`: The wsl executable discovered\n* `rcfile`: The rc file (e.g. `.bashrc`) to source prior to launch selected in the script\n* `launch_script`: The path of the linux launcher script\n* `exec_dir`: The directory in which this command will be run (linux path)\n* `run_in_terminal`: Boolean specifying whether or not this app expects to run in a terminal\n\n## Troubleshooting\n\n### No applications launching\n\nIf no applications are launching at all, it's most likely an issue with either:\n\n* `DISPLAY` not being set correctly\n* `DISPLAY` being set fine, but its destination is not accessible from the WSL environment\n* The X11 server isn't set up to allow access from external hosts (how to configure this will depend on your X11 server\n  so please refer to their documentation)\n\nNote that for this section, you can check which version of WSL you're using with:\n\n    wsl.exe -l --verbose\n\n#### Check WSL1 `$DISPLAY` variable\n\nIf you're running WSL1, the `DISPLAY` variable for WSL1 should simply be `localhost:0.0`\nif this is the default distribution.\n\n#### Check WSL2 `$DISPLAY` variable\n\nUnfortunately for WSL2, it's a little more complicated for now, though I think they're\nplanning on fixing this. You'll need something like this to extract the correct host:\n\n    export DISPLAY=$(grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}'):0.0\n\n### Firewall Rules\n\nThen you need to worry about the firewall. WSL comes up as a public network, but I wouldn't recommend\nallowing all public network traffic to access your X server. So instead, you can go ahead and select\ndefaults when this sort of prompt comes up:\n\n![Security Alert](https://github.com/cascadium/wsl-windows-toolbar-launcher/raw/master/assets/security_alert.png)\n\nNow, irritatingly this will actively add a block rule (rather than simply not add an allow rule) for public networks\nwhich you will need to disable for the next step by going into Windows Defender Firewall -\u003e Inbound Rules and\n**disabling this block rule for TCP on the Public Network**.\n\nIf you don't do the above step, the Block rule will take precedence over the Allow allow rule and you won't get through.\n\nNow, right click on Inbound Rules and select `New Rule...`, select TCP port 6000 (most likely, but verify with display number / X11 server documentation before continuing) and select defaults. This\nwill open up your public network for this port... which is also not what you want. What you want is to only allow traffic\nfrom the WSL subnet. So refresh the list, scroll to your recently created name, right click and go to properties. Now\nunder `Scope`, go to **Remote IP address**, Select `These IP addresses` and add in `172.16.0.0/12` to limit the subnets\nwhich can access this port to the WSL subnet. It should look something like this:\n\n![WSL Subnet Firewall Rule](https://github.com/cascadium/wsl-windows-toolbar-launcher/raw/master/assets/firewall_rule_wsl_subnet.png)\n\nAlternatively you *could* just disable the entire firewall for WSL, but that adds a firewall warning that constantly\nirritates me:\n\n    powershell.exe -Command \"Set-NetFirewallProfile -DisabledInterfaceAliases \\\"vEthernet (WSL)\\\"\"\n\n### Application X not working\n\nDoes the application use dbus? If so, it's recommended to put something like this in your `.bashrc` to satisfy the many\napplications which depend on dbus to function:\n\n    dbus_status=$(service dbus status)\n    if [[ $dbus_status = *\"is not running\"* ]]; then\n      sudo service dbus --full-restart\n    fi\n\nAlso check that the `.bashrc` tweaks are added **before any nastiness** like this in your `.bashrc` which would prevent `DISPLAY` from being set:\n\n    # If not running interactively, don't do anything\n    [ -z \"$PS1\" ] \u0026\u0026 return\n\nYou can do similar with `docker` or any other service which you will need access to, but won't necessarily already be\nrunning in a vanilla WSL installation.\n\nTo debug further, you can run the shortcut directly from the command line from a `cmd` shell:\n\n    wsl.exe -d \u003cyour-wsl-distro\u003e -u \u003cyour-wsl-user\u003e -- source ~/.bashrc ; env; xterm\n\nReplacing xterm with whatever command you're trying to launch. Note the `env` command will\nprint out all environment variables set before running `xterm` in this example, so this should\nhelp you double check if `DISPLAY` is really set correctly. \n\n\n## Raising Issues\n\nIssues may be raised in github issues. Before raising an issue though:\n\n* Verify that you have an X Server running on windows 10. Popular options include X410 or Xming.\n* Verify that you can actually launch X applications from a WSL terminal (e.g. try running xterm).\n\nIf an issue is to be required, please prepare the log output from the command and details on your\nexecution environment. Ideally try and find the `.desktop` file relating to the failing software as well.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcascadium%2Fwsl-windows-toolbar-launcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcascadium%2Fwsl-windows-toolbar-launcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcascadium%2Fwsl-windows-toolbar-launcher/lists"}