{"id":16272179,"url":"https://github.com/eliranwong/wsl2","last_synced_at":"2025-09-06T16:33:23.013Z","repository":{"id":107360694,"uuid":"225736173","full_name":"eliranwong/wsl2","owner":"eliranwong","description":"Notes on setup of Windows Subsystem for Linux (version 2)","archived":false,"fork":false,"pushed_at":"2024-03-26T22:14:31.000Z","size":1447,"stargazers_count":43,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-29T13:45:30.202Z","etag":null,"topics":["gnome-terminal","gui","gui-apps","linux","pengwin-setup","vcxsrv","windows","windows-subsystem","wsl2"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eliranwong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2019-12-03T23:21:02.000Z","updated_at":"2024-11-13T21:34:03.000Z","dependencies_parsed_at":"2024-10-27T21:39:20.118Z","dependency_job_id":"a268c6fe-a7f0-4ec3-a2fe-1dad4798a3be","html_url":"https://github.com/eliranwong/wsl2","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliranwong%2Fwsl2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliranwong%2Fwsl2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliranwong%2Fwsl2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eliranwong%2Fwsl2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eliranwong","download_url":"https://codeload.github.com/eliranwong/wsl2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232133629,"owners_count":18477294,"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":["gnome-terminal","gui","gui-apps","linux","pengwin-setup","vcxsrv","windows","windows-subsystem","wsl2"],"created_at":"2024-10-10T18:16:35.765Z","updated_at":"2025-01-01T22:43:44.802Z","avatar_url":"https://github.com/eliranwong.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Latest\n\nFor setup of WSL2 Ubuntu version and running a Qt for Python application, read:\n\nhttps://github.com/eliranwong/UniqueBible/wiki/Install-UBA-on-Windows-via-WSL2-Ubuntu\n\n# wsl2\nNotes on setup of Windows Subsystem for Linux (version 2)\n\nNotes in this repository mainly describe the setup of pengwin version 1.3.4 in WSL2\n\n# Disclaimer\n\nWe write these notes for personal use.  Please use at your own risk.\n\n# Use Latest Network Drivers\n\nIn our testings, micrsoft \"Windows Update\" app does not detect newer version of wifi driver on one of our devices.  The old driver did cause an issue under WSL2 [e.g. \u003ca href=\"https://github.com/microsoft/WSL/issues/4253\"\u003ea link here\u003c/a\u003e, \u003ca href=\"https://github.com/WhitewaterFoundry/Pengwin/issues/561\"\u003eanother link here\u003c/a\u003e].\n\nIf you use Intel hardware, to make sure you get the latest drivers, go to the following link and install \"Intel Driver \u0026 Support Assistant\":\n\nhttps://www.intel.com/content/www/us/en/support/intel-driver-support-assistant.html\n\nDo a scan with the assistant and install the latest network drivers if newer versions are found.\n\n# Notes on enabling WSL\n\nhttps://docs.microsoft.com/en-us/windows/wsl/install-win10\n\n# Notes on conversion between WSL1 \u0026 WSL2\n\nhttps://learn.microsoft.com/en-us/windows/wsl/install-manual\n\n# Connect USB Drive\n\nhttps://learn.microsoft.com/en-us/windows/wsl/connect-usb\n\n# Setup X410 (PAID)\n\nDPI Scaling \u003e High Quality (Windowed Apps Only)\n\nShared Clipboard \u003e Enable\n\nMiscellaneous Options \u003e Capture Windows Key\n\nTo work with WSL2, select \"Allow Public Access\"\n\nRemarks: Set Windows firewall according to your needs.\n\n# Alternative to X410 - VCXSRV (FREE)\n\nYou may consider VCXSRV as an alternative to X410.\n\nWe do not recommended installing VCXSRV via pengwin-setup.\n\nInstead, we recommend installing VCXSRV via Windows PowerShell (Admin):\n[Reason: It is easier to use XLaunch from start menu for configuration.]\n\n\u003e choco install vcxsrv\n\nTo make \"vcxsrv\" to work with google web engine or QtWebEngine, select from XLaunch \"Native OpenGL\".\n\nTo make \"vcxsrv\" to work with WSL2, select from XLaunch \"Disable Access Control\".\n\n\u003cb\u003eComment:\u003c/b\u003e\n\nIn our testing, windowed apps work better and look nicer in X410, as it offers a feature \"DPI Scaling \u003e High Qaulity\".  You don't need to install VCXSRV if you have X410 installed.\n\n# Autostart Display Server\n\nIt is better to start display server before launching a GUI app.  To start a display server automatically, for example, X410\n\nOpen Windows \"Run\" app, \n\nto open apps folder\n\n\u003e shell:appsfolder\n\nto open startup folder\n\n\u003e shell:startup\n\nTo create link in startup, drag X410 from apps folder to startup folder\n\n# Update Installed Packages\n\n\u003e sudo apt update\u003cbr\u003e\n\u003e sudo apt dist-upgrade\n\n# Edit 00-pengwin.sh\n\n\u003e sudo nano /etc/profile.d/00-pengwin.sh\n\nChange from:\n\n\u003e alias ll='ls -al'\n\nTo:\n\n\u003e alias ll='ls -alh'\n\n# Setup with pengwin-setup\n\n\u003cb\u003eRECOMMENDED:\u003c/b\u003e\n\nGUI \u003e GUILIB\n\nGUI \u003e SYNAPTIC\n\nPROGRAMMING \u003e GO\n\nPROGRAMMING \u003e PYTHONPI\n\nSETTINGS \u003e EXPLORER\n\nSETTINGS \u003e COLORTOOL\n\n\u003cb\u003eNOT RECOMMENDED:\u003c/b\u003e\n\nGUI \u003e FCITX [It breaks in many GUI apps under WSL2]\n\nGUI \u003e HIDPI [instead, use X410 \u003e DPI Scaling \u003e High Quality (Windowed Apps Only)]\n\nEDITORS \u003e CODE [read: https://github.com/eliranwong/wsl2/blob/master/programming/vs_code.md]\n\n# Settings for Launching Linux GUI Apps\n\nThere were mutliple issues about running GUI apps with pengwin version earlier than 1.3.4 under WSL2.  Most know issues had been fixed with pengwin version 1.3.4.\n\nTwo suggestions here:\n\n1) Add the following line to \"~/.profile\", if you need to work with .Xresources, e.g. https://github.com/eliranwong/wsl2/blob/master/terminal/urxvt.md#to-customise:\n\n\u003e xrdb -merge ~/.Xresources\n\n2) To assign QStandardPaths for running Qt applications, app the following lines to file \"~/.profile\":\n\n\u003e mkdir -p /tmp/runtime-$USER\u003cbr\u003e\n\u003e chmod 7700 /tmp/runtime-$USER\u003cbr\u003e\n\u003e export XDG_RUNTIME_DIR=/tmp/runtime-$USER\n\n# Setup Common Tools\n\n\u003e sudo apt install apt-utils build-essential cmake tree wget curl git zip unzip xz-utils nano lib32stdc++6 sqlite3 libsqlite3-dev libasound2 libnss3 libncurses5 libncurses5-dev libgl1-mesa-dev mesa-utils lsb-release binutils dbus-x11 youtube-dl ffmpeg gawk translate-shell opencc rar unrar mlocate\n\n# Examples on Command-line Tools\n\n* Useful tools\n\nhttps://github.com/eliranwong/wsl2/blob/master/cli_tools/Readme.md\n\n* Download Youtube Video / Audio\n\nhttps://github.com/eliranwong/wsl2/blob/master/multimedia/youtube-dl.md\n\n* video conversion:\n\nhttps://github.com/eliranwong/wsl2/blob/master/multimedia/ffmpeg.md\n\n# Setup Input Method\n\n\"fcitx\", bundled with pengwin, is not working in WSL2 at the time of writing.\n\nWe recommend \"ibus\" instead.  For setup of ibus, read:\n\nhttps://github.com/eliranwong/wsl2/blob/master/input_method/ibus.md\n\n# Setup Terminal Apps\n\nFor issues with official pengwin terminal window and alternatives, you may read:\n\nhttps://github.com/eliranwong/wsl2/blob/master/terminal/Readme.md\n\n# Setup Linux GUI File Manager\n\nhttps://github.com/eliranwong/wsl2/blob/master/file_manager/thunar.md\n\n# Open a File on WSL with Default Windows Application\n\nFor example to open a file, say \"my_word_document.docx\", located on WSL, with Microsoft Word installed on Windows:\n\n\u003e powershell.exe start \"my_word_document.doc\"\n\n\u003cb\u003eRemarks: Use double quote \"\" for file names, which contain space characters.\u003c/b\u003e\n\n* To create an alias:\n\n\u003e echo \"alias start='powershell.exe start'\" \u003e\u003e ~/.bashrc\n\n* To create a custom action in Thunar:\n\nName \u0026 Description:\u003cbr\u003e\n\u003e Open with Default Windows Application\n\nCommand:\u003cbr\u003e\n\u003e powershell.exe start \"%n\"\n\nAppearance Conditions:\u003cbr\u003e\n\u003e Text Files, Audio Files, Video Files, Image Files, Other Files\n\nFor more about Thunar: https://github.com/eliranwong/wsl2/blob/master/file_manager/thunar.md\n\n# Open Windows Explorer via Linux Shell\n\n\u003e explorer.exe .\n\n# Open Windows Explorer via Thunar File Manager\n\nhttps://github.com/eliranwong/wsl2/blob/master/file_manager/thunar.md#open-a-folder-with-windows-explorer\n\n\u003cimg src=\"file_manager/open_explorer_from_thunar.png\" /\u003e\n\n# Launch Thunar File Manager from Windows Explorer\n\nhttps://github.com/eliranwong/wsl2/blob/master/file_manager/thunar.md#launch-thunar-from-windows-context-menu\n\n# Lanuch Gnome Terminal from Windows Explorer\n\nhttps://github.com/eliranwong/wsl2/blob/master/terminal/gnome-terminal.md\n\n\u003cimg src=\"terminal/context_menu_open.png\" /\u003e\n\n# Launch Windows Linux Shell from Windows Explorer\n\nOn Windows Explorer,\n\nEnter \"wsl\" on address bar\u003cbr\u003e\n\u003ci\u003eor\u003c/i\u003e\u003cbr\u003e\nright-click and select \"Open with Pengwin\"\u003cbr\u003e\n\u003ci\u003eor\u003c/i\u003e\u003cbr\u003e\nshift \u0026 right-click and select \"Open with Pengwin\"\u003cbr\u003e\n\u003ci\u003eor\u003c/i\u003e\u003cbr\u003e\nshift \u0026 right-click and select \"Open Linux shell here\"\n\n# Launch Linux GUI app from Windows PowerShell\n\ne.g.\n\n\u003e pengwin.exe run \"bash -l -c google-chrome\"\n\n# WSL Utilities \n\n\u003ca href='https://github.com/wslutilities/wslu'\u003eWSL Utilities\u003c/a\u003e are bundled with pengwin.  Read more about these utilities at https://github.com/wslutilities/wslu.\n\nFor example, to open a website, say https://github.com, using Windows default web browser, run\n\n\u003e wslview https://github.com\n\n* \u003cb\u003eTo WSL2 Users\u003c/b\u003e, wslusc, bundled with pengwin version 1.3.4 does not work with WSL2.\n\nUse /usr/local/pengwin-setup.d/generate-shortcut.sh instead.  For example: https://github.com/eliranwong/wsl2/blob/master/bible_apps/desktop.md#create-a-windows-shortcut-recommended-for-pengwin-version-134\n\nAlternatively, you can create a Windows shrotcut directly with Windows GUI.  For example: https://github.com/eliranwong/wsl2/blob/master/bible_apps/desktop.md#create-a-windows-shortcut-directly-on-windows\n\n# Setup Bible Apps\n\nCommand line version of UniqueBible.app:\n\nhttps://github.com/eliranwong/wsl2/blob/master/bible_apps/command_line.md\n\nDesktop version of UniqueBible.app:\n\nhttps://github.com/eliranwong/wsl2/blob/master/bible_apps/desktop.md\n\n# Setup Other GUI Apps\n\nTo install available packages:\n\n\u003e sudo apt install gedit geany geany-plugins rxvt-unicode gnome-terminal thunar thunar-archive-plugin thunar-media-tags-plugin sqlitebrowser firefox-esr flashplugin-nonfree falkon gnome-keyring libsecret* libreoffice gthumb gimp\n\n[Remarks: ibus works with all the above GUI apps tested in both WSL1 \u0026 WSL2 whereas fcitx works only in some applications in WSL1.  At the time of writing, fcitx is broken in WSL2.]\u003cbr\u003e\n[Remarks: Some of GUI apps above, e.g. falkon, work only in version 2 of WSL.]\u003cbr\u003e\n[Remarks: gnome-keyring \u0026 libsecret* are required for running mailspring.]\n\n* Office\u003cbr\u003e\nwps office [https://www.wps.com/download] shows better compatibilities with ms files than libreoffice.  You can also open an office file located on WSL with Microsoft Office installed on Windows.  Read: https://github.com/eliranwong/wsl2#open-a-file-on-wsl-with-default-windows-application\n\n* mail client\u003cbr\u003e\nmailspring is available for download at https://getmailspring.com/. Mailspring works with gmail signin whereas thunderbird doesn't.\nTo verify gmail signin with mailspring, use Linux browser installed in WSL2 instead of using browser installed in Windows directory. Use Firefox / Chrome / Opera instead of falkon for gmail signin verification.\n\n* Web browser\u003cbr\u003e\nIn our testings, chrome and opera browsers work in WSL2, but not in WSL1\u003cbr\u003e\nChrome is available at: https://www.google.com/chrome/\u003cbr\u003e\nOpera is available at: https://www.opera.com/\u003cbr\u003e\nChrome works the best with signin of mutliple gmail accounts.\n\n# GUI for pacakage management\n\n\u003e sudo synaptic\n\n# Fixing Windows Startmenu Shortcuts\n\nFor issues before pengwin version 1.3.4, you may read https://github.com/WhitewaterFoundry/Pengwin/issues/551.  Issues mentioned in the post had been fixed in pengwin version 1.3.4.\n\nAfter installing multiple gui apps, run:\n\n\u003e pengwin-setup\n\nselect GUI \u003e STARTMENU\n\nThe problem with creating shortcuts with pengwin-setup is that existing shortcuts are created again each time you run pengwin-setup \u003e GUI \u003e STARTMENU.  For examples, after installing 10 gui apps and run pengwin-setup \u003e GUI \u003e STARTMENU.  When you install one more gui app, running pengwin-setup \u003e GUI \u003e STARTMENU is ineffective because it creates shortcuts for all 11 gui apps.\n\nA workaround is to use /usr/local/pengwin-setup.d/generate-shortcut.sh directly.  For example: https://github.com/eliranwong/wsl2/blob/master/bible_apps/desktop.md#create-a-windows-shortcut-recommended-for-pengwin-version-134\n\nAlternatively, you can create a Windows shrotcut directly with Windows GUI.  For example: https://github.com/eliranwong/wsl2/blob/master/bible_apps/desktop.md#create-a-windows-shortcut-directly-on-windows\n\n# Use Windows Fonts\n\nWe find that we don't have to to add any fonts on Linux side, as with pengwin, our tested GUI applications can use fonts installed on Windows side directly.\n\nFor examples, we have fonts \"NSimSun\" and \"Calibri\" instalaled on Windows on our device.\n\nWe assign Windows font \"NSimSun\" to a Linux terminal app:\u003cbr\u003e\nhttps://github.com/eliranwong/wsl2/blob/master/terminal/urxvt.md#to-customise\n\nWe assign Windows font \"Calibri\" to a Linux GUI app:\u003cbr\u003e\nhttps://github.com/eliranwong/wsl2/blob/master/bible_apps/desktop.md#change-default-font\n\nTo build font information cache files:\n\n\u003e fc-cache -f -v\n\nTo check all available fonts:\n\n\u003e fc-list\n\n# Additional Fonts\n\nTo install additional fonts, e.g. ubuntu fonts:\n\n1) Download the latest version of Ubuntu Fonts from http://font.ubuntu.com/ or run:\u003cbr\u003e\n\u003e wget https://assets.ubuntu.com/v1/0cef8205-ubuntu-font-family-0.83.zip\n\n2) Unzip font package:\u003cbr\u003e\n\u003e unzip 0cef8205-ubuntu-font-family-0.83.zip\n\n3) Create user fonts directory:\u003cbr\u003e\n\u003e mkdir -p ~/.fonts\n\n4) Copy ubuntu fonts to user fonts directory:\u003cbr\u003e\n\u003e cp -r ubuntu-font-family-0.83/ ~/.fonts\n\n5) Build fonts information cache files:\n\u003e fc-cache -f -v\n\n# Workaround to work with USB drive in WSL2\n\nhttps://github.com/eliranwong/wsl2/blob/master/accessories/usb_drive.md\n\n# Terminate a Distro\n\nTo check the name and version of a distro\n\n\u003e wsl.exe -l -v\n\nTo terminate a distro, e.g.\n\n\u003e wsl.exe -t WLinux\n\n\u003e wsl.exe -t Debian\n\n\u003e wsl.exe -t Ubuntu\n\nUse $WSL_DISTRO_NAME:\n\n\u003e wsl.exe -t $WSL_DISTRO_NAME\n\nTo create an alias, e.g.\n\n\u003e echo 'alias shutdown=\"wsl.exe -t $WSL_DISTRO_NAME\"' \u003e\u003e ~/.bashrc\n\n# Fix Slow Download Speed on Windows 10\n\nOpen Control Panel \u003e Networking and Internet \u003e View network status and tasks and click on Change adapter settings on the left panel. Find the vEthernel (WSL) adapter, right click and select Properties. Click on Configure and open the Advanced tab. Search through each of the properties until you find Large Send Offload Version 2 (IPv4) and Large Send Offload Version 2 (IPv6). Disable both of these properties.\n\nRead https://townsyio.medium.com/wsl2-how-to-fix-download-speed-3edb0c348e29\n\n# Shutdown Everything\n\nImmediately terminates all running distributions and the WSL 2 lightweight utility virtual machine.\n\n\u003e wsl.exe --shutdown\n\n# Restart WSL Service\n\nRun from Windows PowerShell (Admin):\n\n\u003e Get-Service LxssManager | Restart-Service\n\n# Backup \u0026 Restore a WSL Distro\n\nTo backup, open Windows PowerShell and run, e.g.:\n\n\u003e wsl --export WLinux WLinux.tar\n\n\u003e wsl --export Ubuntu Ubuntu.tar\n\n\u003e wsl --export Debian Debian.tar\n\nTo restore, e.g.\n\n\u003e wsl --import WLinux C:\\Users\\Eliran\\WLinux C:\\Users\\Eliran\\WLinux.tar\n\nTo unregister, e.g.\n\n\u003e wsl --unregister WLinux\n\n# Other References\n\nhttps://docs.microsoft.com/en-us/windows/wsl/tutorials/gui-apps\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feliranwong%2Fwsl2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feliranwong%2Fwsl2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feliranwong%2Fwsl2/lists"}