{"id":13442084,"url":"https://github.com/mskyaxl/wsl-terminal","last_synced_at":"2025-05-15T07:06:01.585Z","repository":{"id":48176151,"uuid":"66054270","full_name":"mskyaxl/wsl-terminal","owner":"mskyaxl","description":"Terminal emulator for Windows Subsystem for Linux (WSL)","archived":false,"fork":false,"pushed_at":"2020-09-11T05:43:11.000Z","size":274,"stargazers_count":3129,"open_issues_count":29,"forks_count":160,"subscribers_count":80,"default_branch":"master","last_synced_at":"2025-04-14T12:10:06.111Z","etag":null,"topics":["mintty","terminal-emulator","windows-subsystem-linux","wsl"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/mskyaxl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-19T05:06:32.000Z","updated_at":"2025-04-04T03:38:20.000Z","dependencies_parsed_at":"2022-09-17T14:10:43.588Z","dependency_job_id":null,"html_url":"https://github.com/mskyaxl/wsl-terminal","commit_stats":null,"previous_names":["goreliu/wsl-terminal"],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mskyaxl%2Fwsl-terminal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mskyaxl%2Fwsl-terminal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mskyaxl%2Fwsl-terminal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mskyaxl%2Fwsl-terminal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mskyaxl","download_url":"https://codeload.github.com/mskyaxl/wsl-terminal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254292042,"owners_count":22046426,"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":["mintty","terminal-emulator","windows-subsystem-linux","wsl"],"created_at":"2024-07-31T03:01:41.522Z","updated_at":"2025-05-15T07:05:56.572Z","avatar_url":"https://github.com/mskyaxl.png","language":"Shell","funding_links":[],"categories":["HarmonyOS","Shell"],"sub_categories":["Windows Manager"],"readme":"# wsl-terminal\n\nA terminal emulator for Windows Subsystem for Linux (WSL), based on [mintty](http://mintty.github.io/), [fatty](https://github.com/paolo-sz/fatty) and [wslbridge2](https://github.com/Biswa96/wslbridge2).\n\nAll emojis designed by [OpenMoji](https://openmoji.org/) – the open-source emoji and icon project. License: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/#)\n\n\n[中文页面](https://mskyaxl.github.io/wsl-terminal/README.zh_CN.html)(The Chinese README is no longer maintained)\n\n## Screenshot\n\n![screenshot](https://raw.githubusercontent.com/wiki/mskyaxl/wsl-terminal/images/wsl-terminal-3.png)\n\nMore screenshots [here](https://github.com/mskyaxl/wsl-terminal/wiki/Screenshots).\n\n## Usage\n\n0. Make sure you have 7z installed. On Ubuntu run: ```sudo apt install p7zip-full```, on Archlinux: run ```pacman -S p7zip```\n\n1. Change the directory to the folder where you want to install wsl-terminal to.\n\nMake sure to install wsl-terminal in a the windows filesystem and not in the wsl filesistem. The installation folder needs to be on a local NTFS volume.\n\n* Option 1: If you're in cmd.exe run:\n\n```\nwsl bash -c \"$(wget https://raw.githubusercontent.com/mskyaxl/wsl-terminal/master/scripts/install.sh -qO -)\"\n```\n\n* Option 2: If you're in wsl already run\n\n```\nbash -c \"$(wget https://raw.githubusercontent.com/mskyaxl/wsl-terminal/master/scripts/install.sh -qO -)\"\n```\n\n\nIf you want to install the tabbed version you have to add a ```-t``` as parameter as shown bellow\n```\nbash -c \"$(wget https://raw.githubusercontent.com/mskyaxl/wsl-terminal/master/scripts/install.sh -qO -)\" '' -t\n```\n\n2. Run `open-wsl.exe` to open a WSL terminal in current directory.\n\n3. Run `tools/1-add-open-wsl-terminal-here-menu.js` ([help](https://github.com/mskyaxl/wsl-terminal#tools)) to add a `Open wsl-terminal Here` context menu to `explorer.exe` (Run `tools/1-remove-open-wsl-terminal-here-menu.js` to remove it). If you are using Total Commander, [Use wsl-terminal with Total Commander](https://github.com/mskyaxl/wsl-terminal/wiki/Use-wsl-terminal-with-Total-Commander) may help you.\n\n4. `run-wsl-file.exe` can run any `.sh` (or any others like `.py` `.pl`) script files in wsl-terminal, support `Open With` context menu in `explorer.exe`.\n\n5. `vim.exe` can open any files with vim (in wsl-terminal), support `Open With` context menu in `explorer.exe`. `vim.exe` can be renamed to `emacs.exe` `nvim.exe` `nano.exe` `...` to open files in `emacs` `nvim` `nano` `...`.\n\n## Keyboard shortcuts\n\n| key                        | function                              |\n| -------------------------- | ------------------------------------- |\n| `Alt` + `Enter`            | Fullscreen                            |\n| `Alt` + `F2`               | New window                            |\n| `Alt` + `F3`               | Search text                           |\n| `Ctrl` + `[Shift]` + `Tab` | Switch window                         |\n| `Ctrl` + `=` `+` `-` `0`   | Zoom                                  |\n| `Ctrl` + `Click`           | Open URL or dir/file under the cursor |\n| `Ctrl` + `Right Click`     | Open context menu                     |\n\n[Bind wsl-terminal to a hotkey](https://github.com/mskyaxl/wsl-terminal/wiki/Bind-wsl-terminal-to-a-hotkey).\n\n## Params\n\n### open-wsl\n\n```\nUsage: open-wsl [OPTION]...\n  -a: activate an existing wsl-terminal window.\n      if use_tmux=1, attach the running tmux session.\n  -l: start a login shell and cd to $HOME (doesn't work with use_tmux=1).\n  -c command: run command (e.g. -c \"echo a b; echo c; cat\").\n  -e commands: run commands (e.g. -e echo a b; echo c; cat).\n  -C dir: change directory to a WSL dir (e.g. /home/username).\n  -W dir: change directory to a Windows dir (e.g. c:\\Users\\username).\n  -d distro: switch distros.\n  -b \"options\": pass additional options to wslbridge.\n  -B \"options\": pass additional options to mintty.\n  -h: show help.\n```\n\nFor `-B` and `-b`, see also [mintty params](https://github.com/mskyaxl/wsl-terminal/wiki/mintty-params) and [wslbridge2 params](https://github.com/Biswa96/wslbridge2#options).\n\n### cmdtool (run it in WSL)\n\n```\nUsage: cmdtool [OPTION]...\n  wcmd: run Windows programs with cmd.exe /c.\n  wstart: run Windows programs with cmd.exe /c start.\n  wstartex file|url: like wstart, but use WSL file path.\n  update: check the latest wsl-terminal version, and upgrade it.\n  killall: kill all WSL processes.\n  install dash: install Cygwin dash (for debugging).\n  install busybox: install Cygwin busybox (for debugging).\n```\n\n## Tools\n\nFiles in `tools` directory:\n\n| filename                                    | function                                                            |\n| ------------------------------------------- | ------------------------------------------------------------------- |\n| 1-add-open-wsl-terminal-here-menu.js        | Add `Open wsl-terminal Here` context menu to `explorer.exe`.        |\n| 1-remove-open-wsl-terminal-here-menu.js     | Remove `Open wsl-terminal Here` context menu.                       |\n| 2-add-wsl-terminal-dir-to-path.js           | Add `wsl-terminal` directory to `Path` environment variable.        |\n| 2-remove-wsl-terminal-dir-from-path.js      | Remove `wsl-terminal` directory from `Path` environment variable.   |\n| 3-write-distro-to-config-file.js            | Write distro guids to `etc/wsl-terminal.conf`.                      |\n| 4-create-start-menu-shortcut.js             | Create a start menu shortcut to `open-wsl -C ~`.                    |\n| 4-create-start-menu-shortcut-login-shell.js | Create a start menu shortcut to `open-wsl -l`.                      |\n| 4-remove-all-start-menu-shortcuts.js        | Remove all wsl-terminal start menu shortcuts.                       |\n| 5-add-open-with-vim-menu.js                 | Add `Open with vim in wsl-terminal` context menu.                   |\n| 5-remove-open-with-vim-menu.js              | Remove `Open with vim in wsl-terminal` context menu.                |\n| 6-set-default-shell.bat                     | Set `shell` in `etc/wsl-terminal.conf` to the default shell in WSL. |\n\nDouble click any `.js` file to run it. If it was open by any editor, open it with `Microsoft (R) Windows Based Script Host`, or open a `cmd.exe` in `tools` directory and run `wscript xxx.js`.\n\n## Configuration files\n\n`etc/wsl-terminal.conf` is wsl-terminal config file.\n```\n[config]\ntitle=\"my title\"\nshell=/bin/bash\nuse_tmux=0\n;icon=\n;distro=\n```\n\n`etc/themes/*` are theme files, [use themes](https://github.com/mskyaxl/wsl-terminal/wiki/Use-themes).\n\n`etc/minttyrc` is mintty config file, [mintty tips](https://github.com/mintty/mintty/wiki/Tips).\n\n## Upgrade\n\nOpen `open-wsl.exe` in `wsl-terminal` directory, run `./cmdtool update` to check the latest wsl-terminal version and upgrade it. If the download speed is too slow, you can download `wsl-terminal-v{version}.7z` from [releases](https://github.com/mskyaxl/wsl-terminal/releases) with other tools, and put it into `wsl-terminal` directory, then run `./cmdtool update`.\n\n`wget` and `7z` commands are needed (Ubuntu: `apt install wget p7zip-full`, Archlinux: `pacman -S wget p7zip`) .\n\nConfig files won't be overridden, `etc/wsl-terminal.conf` and `etc/minttyrc` will be placed to `etc/wsl-terminal.conf.pacnew` and `etc/minttyrc.pacnew`. Some `.bak` files will be left in `bin`, because they are running, those files will be removed after the next upgrading.\n\n## Use tmux\n\n1. Install tmux in WSL.\n2. Set `use_tmux=1` in `etc/wsl-terminal.conf`. And set `attach_tmux_locally=1` if the version number is less than `0.8.1`.\n3. Add these lines to `~/.bashrc` (`shell=/bin/bash` in config) or `~/.zshrc` (`shell=/bin/zsh` in config):\n\n```\n[[ -z \"$TMUX\" \u0026\u0026 -n \"$USE_TMUX\" ]] \u0026\u0026 {\n    [[ -n \"$ATTACH_ONLY\" ]] \u0026\u0026 {\n        tmux a 2\u003e/dev/null || {\n            cd \u0026\u0026 exec tmux\n        }\n        exit\n    }\n\n    tmux new-window -c \"$PWD\" 2\u003e/dev/null \u0026\u0026 exec tmux a\n    exec tmux\n}\n```\nIf you're using fish then update your '~/.config/fish/config.fish' (`shell=/bin/fish` in config) with\n\n```\nif [ -z \"$TMUX\" ]; and [ -n \"$USE_TMUX\" ]\n    if [ -n \"$ATTACH_ONLY\" ]\n        if not tmux a 2\u003e/dev/null\n            cd; and exec tmux\n        end\n        exit\n    end\n\n    tmux new-window -c \"$PWD\" 2\u003e/dev/null; and exec tmux a\n    exec tmux\nend\n```\n\nThen `open-wsl` will use tmux.\n\n## Switch distros\n\nUse `open-wsl -d distro` to switch distros:\n\n```\n# list all distros\n\u003e wslconfig /l\nLegacy (Default)\nUbuntu\n\n# use Ubuntu (will run wslconfig /s Ubuntu before mintty)\n\u003e open-wsl -d Ubuntu\n\n# Ubuntu is the default distro now\n\u003e wslconfig /l\nUbuntu (Default)\nkali-linux\n```\n\nOr set `distro` in wsl-terminal.conf (Won't change the default distro).\n\nRun `tools/3-write-distro-to-config-file.js` ([help](https://github.com/mskyaxl/wsl-terminal#tools)), then a msgbox will show the result:\n\n```\nresult has been written to ..\\etc\\wsl-terminal.conf:\n\n;distro=kali-linux\n\n;distro=Ubuntu\n\nremove the ; before distro to use the distro.\n```\n\nIf you want to pass the distro_guid to open-wsl in cmdline:\n\n```\n\n# pass the distro guid to wslbridge\n\u003e open-wsl -b \"-d Ubuntu\"\n```\n\n## Links\n\n[FAQ](https://github.com/mskyaxl/wsl-terminal/wiki/FAQ)\n\n[Issues](https://github.com/mskyaxl/wsl-terminal/issues)\n\n[Releases](https://github.com/mskyaxl/wsl-terminal/releases)\n\n[Wiki](https://github.com/mskyaxl/wsl-terminal/wiki)\n\n## Build\n\n### Prerequisites\n\n* Install WSL and make sure `wget` `tar` `xz` `gzip` `p7zip` are available (Ubuntu: run `apt install wget tar xz-utils gzip p7zip-full`, Archlinux: run `pacman -S wget tar xz gzip p7zip`) are installed in WSL.\n* for the tabbed version: cygwin x64 with the following packages installed `gcc-g++`, `make`, `w32api-headers` (for compiling fatty)\n\n### Build steps\n\n* clone the repo in WSL(to maintain the linux EOL characters) but on windows drive eg (`/mnt/c/Users/\u003cuserName\u003e/work/wsl-terminal`)\n\n* use build.sh to build with the appropiate parameters.\n    ```\n    ➜  wsl-terminal git:(master) scripts/build.sh -h\n    Usage:\n        build.sh -h                 Display this help message.\n        build.sh -a                 Builds wsl-terminal and wsl-terminal-tabbed.\n        build.sh -t                 Builds only wsl-terminal-tabbed(cygwin is required).\n        build.sh                    Builds only wsl-terminal.\n    ```\n\n## Roadmap\n\n1. Bug fixing\n2. add x11 support\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmskyaxl%2Fwsl-terminal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmskyaxl%2Fwsl-terminal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmskyaxl%2Fwsl-terminal/lists"}