├── Makefile ├── Pipfile ├── README.md ├── background.rst ├── conf.py ├── gotchas.rst ├── gui.rst ├── index.rst ├── installation.rst ├── make.bat ├── packages.rst └── update.rst /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | SPHINXPROJ = WindowsSubsystemforLinuxGuide 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -------------------------------------------------------------------------------- /Pipfile: -------------------------------------------------------------------------------- 1 | [[source]] 2 | url = "https://pypi.python.org/simple" 3 | verify_ssl = true 4 | 5 | [packages] 6 | Sphinx = "*" 7 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # wsl-guide 2 | The Hitchhiker's Guide to Bash on Ubuntu on Windows! 3 | 4 | This guide is a work in progress. Please feel free to help! 5 | -------------------------------------------------------------------------------- /background.rst: -------------------------------------------------------------------------------- 1 | Background on WSL (Windows Subsystem for Linux) 2 | =============================================== 3 | 4 | What is WSL? 5 | ------------ 6 | 7 | WSL is a full Ubuntu operating system that you can install on your Windows 10 machine. 8 | 9 | It's Beta Software 10 | ------------------ 11 | 12 | Please keep in mind that this is beta software. This means that any part of it is subject to change, as feedback is collected and improvements are made based on community feedback. 13 | 14 | In fact, if you have any issues you run into you, you can `open a GitHub issue `_ with Microsoft to let them know about it! 15 | 16 | Microsoft's `Creator's Update `_ includes some improvements to the WSL that are not included in the regular release of Windows yet. The biggest one being that you can launch Windows programs from WSL. -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # Windows Subsystem for Linux Guide documentation build configuration file, created by 4 | # sphinx-quickstart on Sat Apr 29 13:21:39 2017. 5 | # 6 | # This file is execfile()d with the current directory set to its 7 | # containing dir. 8 | # 9 | # Note that not all possible configuration values are present in this 10 | # autogenerated file. 11 | # 12 | # All configuration values have a default; values that are commented out 13 | # serve to show the default. 14 | 15 | # If extensions (or modules to document with autodoc) are in another directory, 16 | # add these directories to sys.path here. If the directory is relative to the 17 | # documentation root, use os.path.abspath to make it absolute, like shown here. 18 | # 19 | # import os 20 | # import sys 21 | # sys.path.insert(0, os.path.abspath('.')) 22 | 23 | 24 | # -- General configuration ------------------------------------------------ 25 | 26 | # If your documentation needs a minimal Sphinx version, state it here. 27 | # 28 | # needs_sphinx = '1.0' 29 | 30 | # Add any Sphinx extension module names here, as strings. They can be 31 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 32 | # ones. 33 | extensions = ['sphinx.ext.todo'] 34 | 35 | # Add any paths that contain templates here, relative to this directory. 36 | templates_path = ['_templates'] 37 | 38 | # The suffix(es) of source filenames. 39 | # You can specify multiple suffix as a list of string: 40 | # 41 | # source_suffix = ['.rst', '.md'] 42 | source_suffix = '.rst' 43 | 44 | # The master toctree document. 45 | master_doc = 'index' 46 | 47 | # General information about the project. 48 | project = u'Windows Subsystem for Linux Guide' 49 | copyright = u'2017, Kenneth Reitz' 50 | author = u'Kenneth Reitz' 51 | 52 | # The version info for the project you're documenting, acts as replacement for 53 | # |version| and |release|, also used in various other places throughout the 54 | # built documents. 55 | # 56 | # The short X.Y version. 57 | version = u'' 58 | # The full version, including alpha/beta/rc tags. 59 | release = u'' 60 | 61 | # The language for content autogenerated by Sphinx. Refer to documentation 62 | # for a list of supported languages. 63 | # 64 | # This is also used if you do content translation via gettext catalogs. 65 | # Usually you set "language" from the command line for these cases. 66 | language = None 67 | 68 | # List of patterns, relative to source directory, that match files and 69 | # directories to ignore when looking for source files. 70 | # This patterns also effect to html_static_path and html_extra_path 71 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 72 | 73 | # The name of the Pygments (syntax highlighting) style to use. 74 | pygments_style = 'sphinx' 75 | 76 | # If true, `todo` and `todoList` produce output, else they produce nothing. 77 | todo_include_todos = True 78 | 79 | 80 | # -- Options for HTML output ---------------------------------------------- 81 | 82 | # The theme to use for HTML and HTML Help pages. See the documentation for 83 | # a list of builtin themes. 84 | # 85 | html_theme = 'alabaster' 86 | 87 | # Theme options are theme-specific and customize the look and feel of a theme 88 | # further. For a list of options available for each theme, see the 89 | # documentation. 90 | # 91 | # html_theme_options = {} 92 | 93 | # Add any paths that contain custom static files (such as style sheets) here, 94 | # relative to this directory. They are copied after the builtin static files, 95 | # so a file named "default.css" will overwrite the builtin "default.css". 96 | html_static_path = ['_static'] 97 | 98 | 99 | # -- Options for HTMLHelp output ------------------------------------------ 100 | 101 | # Output file base name for HTML help builder. 102 | htmlhelp_basename = 'WindowsSubsystemforLinuxGuidedoc' 103 | 104 | 105 | # -- Options for LaTeX output --------------------------------------------- 106 | 107 | latex_elements = { 108 | # The paper size ('letterpaper' or 'a4paper'). 109 | # 110 | # 'papersize': 'letterpaper', 111 | 112 | # The font size ('10pt', '11pt' or '12pt'). 113 | # 114 | # 'pointsize': '10pt', 115 | 116 | # Additional stuff for the LaTeX preamble. 117 | # 118 | # 'preamble': '', 119 | 120 | # Latex figure (float) alignment 121 | # 122 | # 'figure_align': 'htbp', 123 | } 124 | 125 | # Grouping the document tree into LaTeX files. List of tuples 126 | # (source start file, target name, title, 127 | # author, documentclass [howto, manual, or own class]). 128 | latex_documents = [ 129 | (master_doc, 'WindowsSubsystemforLinuxGuide.tex', u'Windows Subsystem for Linux Guide Documentation', 130 | u'Kenneth Reitz', 'manual'), 131 | ] 132 | 133 | 134 | # -- Options for manual page output --------------------------------------- 135 | 136 | # One entry per manual page. List of tuples 137 | # (source start file, name, description, authors, manual section). 138 | man_pages = [ 139 | (master_doc, 'windowssubsystemforlinuxguide', u'Windows Subsystem for Linux Guide Documentation', 140 | [author], 1) 141 | ] 142 | 143 | 144 | # -- Options for Texinfo output ------------------------------------------- 145 | 146 | # Grouping the document tree into Texinfo files. List of tuples 147 | # (source start file, target name, title, author, 148 | # dir menu entry, description, category) 149 | texinfo_documents = [ 150 | (master_doc, 'WindowsSubsystemforLinuxGuide', u'Windows Subsystem for Linux Guide Documentation', 151 | author, 'WindowsSubsystemforLinuxGuide', 'One line description of project.', 152 | 'Miscellaneous'), 153 | ] 154 | 155 | 156 | 157 | # -- Options for Epub output ---------------------------------------------- 158 | 159 | # Bibliographic Dublin Core info. 160 | epub_title = project 161 | epub_author = author 162 | epub_publisher = author 163 | epub_copyright = copyright 164 | 165 | # The unique identifier of the text. This can be a ISBN number 166 | # or the project homepage. 167 | # 168 | # epub_identifier = '' 169 | 170 | # A unique identification for the text. 171 | # 172 | # epub_uid = '' 173 | 174 | # A list of files that should not be packed into the epub file. 175 | epub_exclude_files = ['search.html'] 176 | 177 | 178 | html_theme_options = { 179 | 'github_user': 'kennethreitz', 180 | 'github_repo': 'wsl-guide', 181 | 'github_banner': True, 182 | 'github_button': True 183 | } -------------------------------------------------------------------------------- /gotchas.rst: -------------------------------------------------------------------------------- 1 | 2 | Common Gotchas 3 | ============== 4 | 5 | VIM Arrow Keys Don't Work 6 | ------------------------- 7 | 8 | You may notice that by default, VIM's arrow keys don't work on your computer. To fix this, add the following to your ``~/.vimrc``:: 9 | 10 | $ cat ~/.vimrc 11 | set term=builtin_ansi 12 | 13 | Sudo 'Unable to Resolve Host' Warning 14 | ------------------------------------- 15 | 16 | You may notice that every time you run ``sudo something``, your system complains that it cannot resolve it's own hostname, but then continues on anyway. To fix this annoyance, you need to add your system's hostname to ``/etc/hosts``:: 17 | 18 | $ cat /etc/hosts 19 | 127.0.0.1 localhost 20 | 127.0.0.1 nova 21 | ... 22 | 23 | Here, my machine is called 'nova'. 24 | 25 | Connecting to the Linux subsystem via SSH 26 | ----------------------------------------- 27 | 28 | In order to be able to ssh into your Linux subsystem instance follow the steps outlined by Master Azazel in this `thread: `_ 29 | 30 | 1. ``sudo apt-get remove openssh-server`` 31 | 2. ``sudo apt-get install openssh-server`` 32 | 3. ``sudo nano /etc/ssh/sshd_config`` and disallow root login by setting ``PermitRootLogin no`` 33 | 4. Then add a line beneath it that says: ``AllowUsers yourusername`` and make sure ``PasswordAuthentication`` is set to ``yes`` if you want to login using a password. 34 | 5. Disable privilege separation by adding/modifying : ``UsePrivilegeSeparation no`` 35 | 6. ``sudo service ssh --full-restart`` 36 | 7. Connect to your Linux subsystem from Windows using a ssh client like PuTTY. 37 | -------------------------------------------------------------------------------- /gui.rst: -------------------------------------------------------------------------------- 1 | GUI Applications 2 | ================ 3 | 4 | Step 1: Installing an X Server 5 | ------------------------------ 6 | 7 | In order to run GUI applications in WSL, you need to first install an X Server on your Windows machine. 8 | I recommend installing `Xming `_. 9 | 10 | Step 2: Set DISPLAY Environment Variable 11 | ---------------------------------------- 12 | 13 | Next, you have to tell your WSL environment to use the X Server by setting the ``DISPLAY`` environment variable. 14 | 15 | I added the following to my ``~/.bashrc``:: 16 | 17 | export DISPLAY=:0 18 | 19 | 20 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. Windows Subsystem for Linux Guide documentation master file, created by 2 | sphinx-quickstart on Sat Apr 29 13:21:39 2017. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | The Windows Subsystem for Linux Guide! 7 | ====================================== 8 | 9 | Greetings, Earthling! Welcome to The Hitchhiker’s Guide to the Windows Subsystem for Linux (WSL). 10 | 11 | **This is a living, breathing guide**. If you’d like to contribute, `fork us on GitHub `_! 12 | 13 | This guide is also available in `Chinese `_. 14 | 15 | This handcrafted guide exists to provide both novice and expert Windows and Linux developers a best practice handbook to the installation, configuration, and usage of WSL (Bash on Ubuntu on Windows) on a daily basis. 16 | 17 | .. toctree:: 18 | :maxdepth: 2 19 | :caption: Contents: 20 | 21 | background 22 | installation 23 | update 24 | gotchas 25 | gui 26 | packages 27 | 28 | Indices and tables 29 | ================== 30 | 31 | * :ref:`genindex` 32 | * :ref:`modindex` 33 | * :ref:`search` 34 | -------------------------------------------------------------------------------- /installation.rst: -------------------------------------------------------------------------------- 1 | Installing WSL (Bash on Ubuntu on Windows) 2 | ========================================== 3 | 4 | This document provides step-by-step instructions for installing WSL on your Windows machine. 5 | 6 | Step 1: Enable Developer Mode 7 | ----------------------------- 8 | 9 | The first thing you need to do is enable developer mode on your Windows machine. 10 | 11 | Go to **Settings -> Update and Security -> For developers**, and click "Developer mode". 12 | 13 | Step 2: Install WSL 14 | ------------------- 15 | 16 | Next, you need to install WSL. 17 | 18 | Go to the Start Menu and search for "turn windows features on or off". 19 | Select that, then check the "Windows Subsystem for Linux (Beta)" checkbox. 20 | 21 | Hit OK. Restart your computer. 22 | 23 | Step 3: Create a Unix Account 24 | ----------------------------- 25 | 26 | Next, we need to activate WSL from the command-line. Open up a Command Prompt and run the following command:: 27 | 28 | > bash 29 | 30 | This will setup your Linux environment on Windows! If you see a blank screen at any point during this process, hit enter, and you'll be prompted to create a new username for your Linux account. 31 | 32 | Step 4: Enjoy! 33 | -------------- -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=. 11 | set BUILDDIR=_build 12 | set SPHINXPROJ=WindowsSubsystemforLinuxGuide 13 | 14 | if "%1" == "" goto help 15 | 16 | %SPHINXBUILD% >NUL 2>NUL 17 | if errorlevel 9009 ( 18 | echo. 19 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 20 | echo.installed, then set the SPHINXBUILD environment variable to point 21 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 22 | echo.may add the Sphinx directory to PATH. 23 | echo. 24 | echo.If you don't have Sphinx installed, grab it from 25 | echo.http://sphinx-doc.org/ 26 | exit /b 1 27 | ) 28 | 29 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% 30 | goto end 31 | 32 | :help 33 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% 34 | 35 | :end 36 | popd 37 | -------------------------------------------------------------------------------- /packages.rst: -------------------------------------------------------------------------------- 1 | Fun Packages to Install 2 | ======================= 3 | 4 | 5 | Changing Your Shell 6 | ------------------- -------------------------------------------------------------------------------- /update.rst: -------------------------------------------------------------------------------- 1 | Updating WSL 2 | ============ 3 | 4 | Updating Packages in WSL 5 | ------------------------ 6 | 7 | Because WSL uses a standard Ubuntu installation, upgrading your packages should look very familiar:: 8 | 9 | $ sudo apt-get update 10 | $ sudo apt-get upgrade 11 | 12 | Updating the Ubuntu OS 13 | ---------------------- 14 | 15 | You can aso upgrade to the latest version of Ubuntu with the following command (caution, this will take quite some time)!:: 16 | 17 | $ sudo -S apt-mark hold procps strace sudo 18 | $ sudo -S env RELEASE_UPGRADER_NO_SCREEN=1 do-release-upgrade 19 | 20 | And, it works, just as expected! 21 | --------------------------------------------------------------------------------