{"id":13451071,"url":"https://github.com/mintty/wsltty","last_synced_at":"2025-05-14T02:04:09.667Z","repository":{"id":40244147,"uuid":"67928223","full_name":"mintty/wsltty","owner":"mintty","description":"Mintty as a terminal for Bash on Ubuntu on Windows / WSL","archived":false,"fork":false,"pushed_at":"2025-03-29T16:37:12.000Z","size":345,"stargazers_count":3130,"open_issues_count":29,"forks_count":105,"subscribers_count":55,"default_branch":"master","last_synced_at":"2025-04-10T19:50:47.928Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mintty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.mintty","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,"zenodo":null}},"created_at":"2016-09-11T12:18:51.000Z","updated_at":"2025-04-07T19:21:23.000Z","dependencies_parsed_at":"2024-06-28T23:28:04.817Z","dependency_job_id":"20ac2a07-6cf7-4182-9871-19ed3d6909d8","html_url":"https://github.com/mintty/wsltty","commit_stats":null,"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintty%2Fwsltty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintty%2Fwsltty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintty%2Fwsltty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintty%2Fwsltty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mintty","download_url":"https://codeload.github.com/mintty/wsltty/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254052667,"owners_count":22006716,"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":[],"created_at":"2024-07-31T07:00:47.249Z","updated_at":"2025-05-14T02:04:09.642Z","avatar_url":"https://github.com/mintty.png","language":"C","funding_links":[],"categories":["C","Tool","Shell","Uncategorized","WSL Tools"],"sub_categories":["Miscs","Uncategorized","10. GUI Apps"],"readme":"Mintty as a terminal for WSL (Windows Subsystem for Linux).\n\n\u003cimg align=right src=wsltty.png\u003e\n\n### Overview ###\n\nWSLtty components\n* wsltty package components (see below) in the user’s local application folder \n  `%LOCALAPPDATA%`\n* a wsltty configuration directory in the user’s application folder `%APPDATA%`\n  (“home”-located configuration files from a previously installed version \n  will be migrated to the new default location)\n* Start Menu shortcuts to start WSL terminals\n* Desktop shorcut to start a terminal for the default WSL distribution\n* `*.bat` scripts to invoke WSL terminals from the command line\n* optional context menu entries for Windows Explorer to start WSL terminals in the respective folder\n* install/uninstall context menu items from Start Menu subfolder `WSLtty`\n\n---\n\n### Requirements ###\n\nTo connect to WSL, wsltty uses wslbridge2, which uses undocumented \nWindows APIs that have been changed various times, so wslbridge2 needed \nto catch up with incompatible changes, particularly to support WSL V2.\n(See e.g. issue #343; to work with WSL V2, wsltty 2.0.0 needed a WSL update \nto [release 1.3.17](https://github.com/microsoft/WSL/releases/tag/1.3.17).)\n\nSince release 3.0.5, WSLtty requires Windows version 1809 (the November 2018 release).\n\nBy end of 2024, wsltty works again with recent updates of the WSL subsystem.\n\n---\n\n### Installation from this repository ###\n\n#### WSLtty installer ([Download](https://github.com/mintty/wsltty/releases) standalone installation) ####\n\nFrom the [release downloads](https://github.com/mintty/wsltty/releases), \nrun the wsltty-VERSION-x86_64-install.exe installer to install \nthe components listed above. Make sure to select a 64-bit installer \non a 64-bit system.\nIf Windows complains with a “Windows protected your PC” popup, \nyou may need to click “Run anyway” to proceed with the installation.\nYou may need to open the Properties of the installer first, tab “General” \nsection “Security” (if available) and select “Unblock”, \nto enable the “Run anyway” button.\n\n#### WSLtty Portable installer\n\nFor a portable installation, e.g. on a USB stick, choose the \n“-install-portable.exe” file for download. Installation will prompt \nfor a portable installation folder interactively. \nFor example, choosing `U:\\opt` will create and use folder \n`U:\\opt\\wsltty` both as installation directory and configuration directory.\nPortable installation does not install any start menu or desktop shortcuts \nand no context menu entries. It creates a shortcut in the selected \nportable installation folder to start the default WSL distribution.\n\nNote: For an update installation, either the parent directory or the target \ndirectory itself can be selected.\n\nNote: If you rename or move the installation directory, the icon of the \n“WSL Terminal Portable” shortcut will not work anymore; re-run the \ninstall-portable.bat script in the installation folder to refresh it.\n\n#### Installation from archive ####\n\nIn case a local anti-virus guard barfs about the wsltty installer, the \nrelease also contains a `.cab` file. Download it, open it, extract its files \nto some temporary deployment directory, and invoke `install.bat` from there, \nor `install-portable.bat` for a portable installation.\n\n#### Quiet installer ####\n\nThe wsltty-VERSION-x86_64-install-quiet.exe installer is intended for \nintegration in another installation framework.\n\n#### Installation from source repository ####\n\nCheckout the wsltty repository, or download the source archive, unpack and rename the directory to `wsltty`.\nInstall Alpine WSL from the Microsoft Store.\nInvoke `make build`, then `make install`.\n\nNote this has to be done within a Cygwin environment. A minimal Cygwin \nenvironment for this purpose would be installed with the \n[Cygwin installer](https://cygwin.com/setup-x86_64.exe) \nfrom [cygwin.com](https://cygwin.com/), \nwith additional packages `make`, `gcc-g++`, `unzip`, `zoo`, `patch`, (`lcab`).\n\n#### Build installers ####\n\nInstall a minimal Cygwin environment plus the additional packages as \nlisted for «Installation from source repository».\nInvoke `make pkg` or just `make`.\n\n#### Installation to non-default locations ####\n\n(For experts)\nWithin the installation process, provide parameters to the script `install.bat`.\nThe optional first parameter designates the installation target,\nthe optional second parameter designates the configuration directory.\n\n### Installation with other package management environments ###\n\nNote: These are 3rd-party packages, not managed by this repository.\n\n#### Windows Package Manager ####\n\n([Check package](https://github.com/microsoft/winget-pkgs/tree/master/manifests/m/Mintty/WSLtty))\nTo install wsltty from the \n[Windows Package Manager Community Repository](https://github.com/microsoft/winget-pkgs), \ninvoke one of\n* `winget install wsltty`\n* `winget upgrade wsltty`\n\n#### Chocolatey ####\n\n([Check package](https://community.chocolatey.org/packages/wsltty))\nIf you use the [Chocolatey package manager](https://chocolatey.org/), \ninvoke one of\n* `choco install wsltty`\n* `choco upgrade wsltty`\n\n#### Scoop ####\n\n([Check package](https://scoop.sh/#/apps?q=wsltty))\nIf you use the [Scoop package manager](https://scoop.sh/), \n* `scoop bucket add extras`\n\nthen, invoke one of\n* `scoop install wsltty`\n* `scoop update wsltty`\n\n### Uninstallation ###\n\nTo uninstall wsltty desktop, start menu, and context menu integration:\nOpen a Windows `cmd`, go into the wsltty installation folder:\n`cd %LOCALAPPDATA%\\wsltty` and run the `uninstall` script.\nTo uninstall wsltty software completely, remove the installation folder manually.\n\n---\n\n### Invocation ###\n\nWSLtty can be invoked with\n* installed Start Menu shortcuts (or Desktop shortcuts if copied there)\n* *.bat scripts (optionally with WSL command as parameters) (see [Command line scripts](#command-line-scripts-wslbat) below)\n* Explorer context menu (if installed from the Start Menu `WSLtty` subfolder)\n\nStarting the mintty terminal directly from the WSLtty installation location \nis discouraged because that would bypass essential options.\n\n#### WSL V2 ####\n\nTerminal communication with WSL via its modes V1 or V2 is handled \nautomatically by wsltty (mintty and the wslbridge2 gateway).\n\n#### Starting issues ####\n\nIf wsltty fails with an \n`Error: Could not fork child process: Resource temporarily unavailable`...,\nits runtime may be affected by some over-ambitious virus defense strategy.\nFor example, with Windows Defender, option “Force randomization for images” \nshould be disabled.\n\nIf wsltty fails with an error message that mentions a disk mount path (e.g. `/mnt/c`),\nworkarounds may be the shutdown of the WSL V2 virtual machine (`wsl --shutdown` on the distro) \nor turning off “fast startup” in the Windows power settings (#246, #248).\n\n#### WSL shell starting issues ####\n\nWith WSL V2, an additional background shell is run which may cause trouble \nfor example when setting up automatic interaction between Windows side and \nWSL side \n(see https://github.com/mintty/wsltty/issues/197#issuecomment-687030527).\nAs a workaround, the following may be added to (the beginning of) the \nWSL shell initialization script `.bashrc` (adapt for other shells):\n```\n    # work around https://github.com/mintty/wsltty/issues/197\n    if [[ -n \"$WSL_DISTRO_NAME\" ]]; then\n      command -v cmd.exe \u003e /dev/null || exit\n    fi\n```\n\n---\n\n### Configuration ###\n\n#### Start Menu and Desktop shortcuts ####\n\nIn the Start Menu, the following shortcuts are installed:\n* Shortcut \u003cimg align=absmiddle height=40 src=tux1.png\u003e`WSL Terminal` to start the default WSL distribution (as configured with the Windows tool `wslconfig` or `wsl -s`)\n* For each installed WSL distribution, for example `Ubuntu`, a shortcut like \u003cimg align=absmiddle height=40 src=ubuntu1.png\u003e`Ubuntu Terminal` to start in the WSL user home\n\nIn the Start Menu subfolder WSLtty, the following additional shortcuts are installed:\n* Shortcut \u003cimg align=absmiddle height=40 src=tux1.png\u003e`WSL Terminal %` to start the default WSL distribution in the Windows %USERPROFILE% home\n* For each installed WSL distribution, for example `Ubuntu`, a shortcut like \u003cimg align=absmiddle height=40 src=ubuntu1.png\u003e`Ubuntu Terminal %` to start in the Windows %USERPROFILE% home\n\nOne Desktop shortcut is installed:\n* Shortcut \u003cimg align=absmiddle height=40 src=tux1.png\u003e`WSL Terminal` to start the default WSL distribution (as configured with the Windows tool `wslconfig` or `wsl -s`)\n\nOther, distribution-specific shortcuts can be copied to the desktop \nfrom the Start Menu if desired.\n\nThe Start menu folder WSLtty contains the link \n\u003cimg align=absmiddle height=25 src=https://user-images.githubusercontent.com/12740416/57078483-a7846a00-6cee-11e9-9c5e-8c2e9e56cae4.png\u003e`configure WSL shortcuts`.\nThis function is initially run when wsltty is installed.\nIt should be rerun after adding or removing WSL distributions, \nin order to create the respective set of shortcuts in the Start menu.\n\n#### Command line scripts `wsl*.bat` ####\n\nWSLtty installs the following scripts into `%LOCALAPPDATA%\\Microsoft\\WindowsApps` \n(and a copy in its application folder `%LOCALAPPDATA%\\wsltty`):\n\n* For each installed WSL distribution, e.g. Ubuntu, a command script like `Ubuntu.bat` to start in the current folder/directory\n* For each installed WSL distribution, e.g. Ubuntu, a command script like `Ubuntu~.bat` to start in the WSL user home\n* `WSL.bat` and `WSL~.bat` to start the default WSL distribution\n\nThe scripts accept an optional invocation command (since 3.7.8).\n\nGiven that `%LOCALAPPDATA%\\Microsoft\\WindowsApps` is in your PATH,\nthe scripts can be invoked from cmd.exe, PowerShell, or via WIN+R.\n\n#### Context menu entries ####\n\nWSLtty provides context menu entries for all installed WSL distributions \nand one for the configured default distribution,\nto start a respective WSL terminal in a specific folder from an Explorer window.\nThey are not installed by default.\n\nTo add launch entries for the default or all WSL distributions to the \nExplorer context menu, or remove them, run the respective script from the \nStart Menu subfolder `WSLtty`:\n* \u003cimg align=absmiddle height=25 src=https://user-images.githubusercontent.com/12740416/57078483-a7846a00-6cee-11e9-9c5e-8c2e9e56cae4.png\u003e`add default to context menu`\n  adds context menu entries for the default WSL distribution\n* \u003cimg align=absmiddle height=25 src=https://user-images.githubusercontent.com/12740416/57078483-a7846a00-6cee-11e9-9c5e-8c2e9e56cae4.png\u003e`add to context menu`\n  adds context menu entries for all WSL distributions\n* \u003cimg align=absmiddle height=25 src=https://user-images.githubusercontent.com/12740416/57078483-a7846a00-6cee-11e9-9c5e-8c2e9e56cae4.png\u003e`remove from context menu`\n  removes context menu entries for WSL distributions\n\n#### Icon ####\n\nWsltty installation and the mintty terminal try to use the icon of the \nrespective WSL distribution. If it cannot be determined, a penguin icon \nis used as a fallback. You can replace it with your preferred default icon \nby replacing the icon file `%LOCALAPPDATA%\\wsltty\\wsl.ico`.\n\n#### Mintty settings ####\n\nMintty can maintain its configuration file in various locations, \nwith the following precedence:\n* file given with mintty option `-c` (not used by wsltty default installation)\n* file `config` in directory given with mintty option `--configdir`\n  * **`%APPDATA%\\wsltty\\config`** in the default wsltty installation\n* `%HOME%\\.minttyrc` (usage deprecated with wsltty)\n* `%HOME%\\.config\\mintty\\config` (usage deprecated with wsltty)\n* common config file for all mintty installation instances\n  * **`%APPDATA%\\mintty\\config`**\n* `%LOCALAPPDATA%\\wsltty\\etc\\minttyrc` (usage deprecated with wsltty)\n\nNote:\n* `%APPDATA%\\wsltty\\config` is the user configuration file location. \n  Further subdirectories of `%APPDATA%\\wsltty` are used for language, \n  themes, and sounds resource configuration. \n  Note the distinction from `%LOCALAPPDATA%\\wsltty` which is the default \n  wsltty software installation location.\n* The `%APPDATA%\\mintty\\config` option provides the possibility to \n  maintain common mintty settings for various installations (like \n  wsltty, Cygwin, MinGW/msys, Git for Windows, MinEd for Windows).\n* (About deprecated options) By default, `%HOME%` would refer to the \n  root directory of the cygwin standalone installation hosting wsltty. \n  So `%HOME%` would mean `%LOCALAPPDATA%\\wsltty\\home\\%USERNAME%`.\n  If you define `HOME` at Windows level, this changes accordingly.\n  Note, however, that the WSL `$HOME` is a completely different setting.\n\n#### Emoji deployment ####\n\nMintty and the wsltty package do not bundle actual emoji graphics but \nthere are scripts to support easy download and deployment.\nIf you have another instance of mintty installed (e.g. in cygwin) \nand have emojis deployed already in the common config folder \n`%APPDATA%\\mintty\\emojis`, they will be reused by wsltty.\n\nTo deploy emojis standalone for wsltty, use the scripts installed in \n`%APPDATA%\\wsltty\\emojis` within WSL:\n* `cd $(wslpath \"$APPDATA/wsltty/emojis\")`\n* `getemojis` to provide emoji graphics as listed by Unicode.org\n* `getflags` to provide emoji flag graphics (extending Unicode dynamically) from various sources\n\n#### Shell selection and Login shell ####\n\nThe WSLtty deployment does not impose a shell preference;\nit invokes the user’s default shell in login mode by the final `-` parameter:\n* `%LOCALAPPDATA%\\wsltty\\bin\\mintty.exe --WSL= --configdir=\"%APPDATA%\\wsltty\" -`\n\nYou may tweak shortcuts, scripts, or context menu entries as follows:\n\nTo launch a default shell in non-login mode, remove the final dash.\n\nTo invoke your preferred shell, replace the final dash with \na shell pathname and an optional `-l` parameter \n* `%LOCALAPPDATA%\\wsltty\\bin\\mintty.exe --WSL= --configdir=\"%APPDATA%\\wsltty\" /bin/bash -l`\n\n---\n\n### WSL locale setup and character encoding ###\n\nCharacter encoding setup by locale setting is propagated from the terminal \ntowards WSL. So you can select your favourite locale with configuration \noptions or with command-line options, for example in a copied dedicated \ndesktop shortcut.\n\nIf for example you wish to run WSL in GB18030 encoding, you may set options\n`Locale=zh_CN` and `Charset=GB18030` and the WSL shell will adopt that \nsetting, provided that the selected locale is configured to be available \nin the locale database of the WSL distribution.\nThis can be achieved in Ubuntu with the following commands:\n* `sudo mkdir -p /var/lib/locales/supported.d`\n* `sudo echo zh_CN.GB18030 GB18030 \u003e\u003e /var/lib/locales/supported.d/local`\n* `sudo locale-gen`\n\n---\n\n### Components and Credits ###\n\nFor mintty, see the [Mintty homepage](http://mintty.github.io/) \n(with further screenshots), \nthe [Mintty manual page](http://mintty.github.io/mintty.1.html), \n\u003cbr\u003eand the [Mintty Wiki](https://github.com/mintty/mintty/wiki), \nincluding a [Hints and Tips page](https://github.com/mintty/mintty/wiki/Tips).\n\nIt is based on [Cygwin](http://cygwin.com) \nand includes its runtime library ([sources](http://mirrors.dotsrc.org/cygwin/x86/release/cygwin)).\n\nFor interacting with WSL, [wslbridge](https://github.com/rprichard/wslbridge)\nused to be the gateway prototype.\nMany thanks for this enabling gateway go to Ryan Prichard.\n\nFor recent changes in WSL, particularly WSL mode V2, the new gateway \n[wslbridge2](https://github.com/Biswa96/wslbridge2) is used instead.\nMany thanks for this further development and maintenance go to Biswapriyo Nath.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmintty%2Fwsltty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmintty%2Fwsltty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmintty%2Fwsltty/lists"}