• Docker Windows 10 Home 1903
• Docker Windows 10 Home Hyper-v
• Docker Windows 10 Home Virtualbox
• Docker Win10 Home Vs
• Docker Windows 10 Home Wsl
• Docker Windows 10 Home Wsl2

There's a file at the path C: ProgramData Docker config daemon.json. Add the line: 'dns': '8.8.8.8' in the JSON object. Ideally, replace it with your actual DNS server. 8.8.8.8 is just a well known DNS server, so it should work. After adding that line, restart the Docker daemon. You can use the context menu from the system tray for that. From now on we can run Docker commands regarding Windows containers with docker -c win (example: docker -c win ps or docker -c win version). Finally, let’s run a test container. As said before, you have to take care that the container base image that you want to run (from Docker Hub / the registry) matches the Windows version that you use.

• Windows version support policy
• Windows troubleshooting
  • I get a PathTooLongException during my builds on Windows

To install and run GitLab Runner on Windows you need:

• Git, which can be installed from the official site
• A password for your user account, if you want to run it under your useraccount rather than the Built-in System Account.

Installation

1. Create a folder somewhere in your system, ex.: C:GitLab-Runner.
2. Download the binary for 64-bit or 32-bit and put it into the folder youcreated. The following assumes you have renamed the binary to gitlab-runner.exe (optional).You can download a binary for every available version as described inBleeding Edge - download any other taggedrelease.
3. Make sure to restrict the Write permissions on the GitLab Runner directory and executable.If you do not set these permissions, regular users can replace the executable with their own and run arbitrary code with elevated privileges.
4. Run an elevated command prompt:
5. Register a runner.

6. Install GitLab Runner as a service and start it. You can either run the serviceusing the Built-in System Account (recommended) or using a user account.

   Run service using Built-in System Account (under directory created in step 1. from above, ex.: C:GitLab-Runner)

   Run service using user account (under directory created in step 1. from above, ex.: C:GitLab-Runner)

   You have to enter a valid password for the current user account, becauseit’s required to start the service by Windows:

   See the troubleshooting section if you encounter anyerrors during the GitLab Runner installation.

7. (Optional) Update the runner’s concurrent value in C:GitLab-Runnerconfig.tomlto allow multiple concurrent jobs as detailed in advanced configuration details.Additionally, you can use the advanced configuration details to update yourshell executor to use Bash or PowerShell rather than Batch.

Voila! Runner is installed, running, and will start again after each system reboot.Logs are stored in Windows Event Log.

Update

1. Stop the service (you need an elevated command prompt as before):

2. Download the binary for 64-bit or 32-bit and replace runner’s executable.You can download a binary for every available version as described inBleeding Edge - download any other tagged release.

3. Start the service:

Uninstall

From an elevated command prompt:

Windows version support policy

We follow the same lifecycle policy as Microsoft’s ServicingChannels.

This means that we support:

• Long-Term ServicingChannel,versions for 5 years after their release date. Note that we don’tsupport versions that are on extended support.
• Semi-AnnualChannelversions for 18 months after their release date. We don’t supportthese versions after mainstream support ends.

This is the case for both the Windows binaries that wedistribute, and also for the Dockerexecutor.

After a Windows version no longer receives mainstream support fromMicrosoft, we officially deprecate theversion andremove it in the next major change. For example, in 12.x we startedsupporting Windows1803because it came out on 2018-04-30. Mainstream support ended on2019-11-12, so we deprecated Windows 1803 in 12.x and it wasremoved inGitLab 13.0.

As a single source of truth we usehttps://docs.microsoft.com/en-us/lifecycle/products/ which specifiesboth the release and mainstream support dates.

Future releases

Microsoft releases new Windows Server products in the Semi-AnnualChanneltwice a year, and every 2 - 3 years a new major version of Windows Severis released in the Long-Term Servicing Channel(LTSC).

GitLab aims to test and release new GitLab Runner helper images thatinclude the latest Windows Server version (Semi-Annual Channel) within 1month of the official Microsoft release date. Refer to the WindowsServer current versions by servicing optionlistfor availability dates.

Windows troubleshooting

Make sure that you read the FAQ section which describessome of the most common problems with GitLab Runner.

If you encounter an error like The account name is invalid try to add . before the username:

If you encounter a The service did not start due to a logon failure errorwhile starting the service, please look in the FAQ to check how to resolve the problem.

If you don’t have a Windows Password, the GitLab Runner service won’t start but you canuse the Built-in System Account.

If you have issues with the Built-in System Account, please readConfigure the Service to Start Up with the Built-in System Accounton Microsoft’s support website.

Get runner logs

When you run .gitlab-runner.exe install it installs gitlab-runneras a Windows service. You can find the logs in the Event Viewerwith the provider name gitlab-runner.

If you don’t have access to the GUI, in PowerShell, you can runGet-WinEvent.

I get a PathTooLongException during my builds on Windows

This is caused by tools like npm which will sometimes generate directory structureswith paths more than 260 characters in length. There are two possible fixes you canadopt to solve the problem.

a) Use Git with core.longpaths enabled

You can avoid the problem by using Git to clean your directory structure, first rungit config --system core.longpaths true from the command line and then set yourproject to use git fetch from the GitLab CI project settings page.

b) Use NTFSSecurity tools for PowerShell

The NTFSSecurity PowerShell module providesa Remove-Item2 method which supports long paths. GitLab Runner willdetect it if it is available and automatically make use of it.

I can’t run Windows BASH scripts; I’m getting The system cannot find the batch label specified - buildscript

You need to prepend call to your Batch file line in .gitlab-ci.yml so that it looks like call C:pathtotest.bat. Hereis a more complete example:

Additional info can be found under issue #1025.

How can I get colored output on the web terminal?

Short answer:

Make sure that you have the ANSI color codes in your program’s output. For the purposes of text formatting, assume that you’rerunning in a UNIX ANSI terminal emulator (because that’s what the webUI’s output is).

Long Answer:

The web interface for GitLab CI emulates a UNIX ANSI terminal (at least partially). The gitlab-runner pipes any output from the builddirectly to the web interface. That means that any ANSI color codes that are present will be honored.

Older versions of Windows’ CMD terminal (before Win10 version 1511) do not supportANSI color codes - they use win32 (ANSI.SYS) calls instead which are not present inthe string to be displayed. When writing cross-platform programs, a developer will typically use ANSI color codes by default and convertthem to win32 calls when running on a Windows system (example: Colorama).

If your program is doing the above, then you need to disable that conversion for the CI builds so that the ANSI codes remain in the string.

See GitLab CI YAML docsfor an example using PowerShell and issue #332for more information.

The service did not start due to a logon failure error when starting service

When installing and starting the GitLab Runner service on Windows you canmeet with such error:

This error can occur when the user used to execute the service doesn’t havethe SeServiceLogonRight permission. In this case, you need to add thispermission for the chosen user and then try to start the service again.

1. Go to Control Panel > System and Security > Administrative Tools.
2. Open the Local Security Policy tool.
3. Choose the Security Settings > Local Policies > User Rights Assignment on thelist on the left.
4. Open the Log on as a service on the list on the right.
5. Click the Add User or Group… button.
6. Add the user (“by hand” or using Advanced… button) and apply the settings.

According to Microsoft’s documentationthis should work for: Windows Vista, Windows Server 2008, Windows 7, Windows 8.1,Windows Server 2008 R2, Windows Server 2012 R2, Windows Server 2012, and Windows 8.

The Local Security Policy tool may be not available in someWindows versions - for example in “Home Edition” variant of each version.

After adding the SeServiceLogonRight for the user used in service configuration,the command gitlab-runner start should finish without failuresand the service should be started properly.

Job marked as success and terminated midway using Kubernetes executor

Please see Job execution.

Docker executor: unsupported Windows Version

GitLab Runner checks the version of Windows Server to verify that it’s supported.

It does this by running docker info.

If GitLab Runner fails to start with the following error, but with no WindowsServer version specified, then the likely root cause is that the Dockerversion is too old.

The error should contain detailed information about the Windows Serverversion, which is then compared with the versions that GitLab Runner supports.

Docker 17.06.2 on Windows Server 1909 returns the following in the outputof docker info.

The fix in this case is to upgrade the Docker version. Read more about supportedDocker versions.

I’m using a mapped network drive and my build cannot find the correct path

If GitLab Runner is not being run under an administrator account and instead is using astandard user account, mapped network drives cannot be used and you’ll receive an error statingThe system cannot find the path specified. This is because using a service logon sessioncreates some limitationson accessing resources for security. Use theUNC pathof your drive instead.

The build container is unable to connect to service containers

Network-per-buildis required to use services with Windows containers. Ensure that the FF_NETWORK_PER_BUILDfeature flag is set.

Help & feedback

Get Help

If you didn't find what you were looking for,search the docs.

If you want help with something specific and could use community support,post on the GitLab forum.

For problems setting up or using this feature (depending on your GitLabsubscription).

There are two options available for installing Windows Subsystem for Linux (WSL):

• Simplified install(preview release): wsl --install

  The wsl --install simplified install command requires that you join the Windows Insiders Program and install a preview build of Windows 10 (OS build 20262 or higher), but eliminates the need to follow the manual install steps. All you need to do is open a command window with administrator privileges and run wsl --install, after a restart you will be ready to use WSL.

• Manual install: Follow the six steps listed below.

  The manual install steps for WSL are listed below and can be used to install Linux on any version of Windows 10.

Note

If you run into an issue during the install process, check the Troubleshooting installation section at the bottom of this page.

Simplified Installation for Windows Insiders

The installation process for Windows Subsystem for Linux has been significantly improved in the latest Windows Insiders preview builds of Windows 10, replacing the manual steps below with a single command.

In order to use the wsl --install simplified install command, you must:

• Join the Windows Insiders Program
• Install a preview build of Windows 10 (OS build 20262 or higher).
• Open a command line windows with Administrator privileges

Once those requirements are met, to install WSL:

• Enter this command in the command line you've opened in Admin mode: wsl.exe --install
• Restart your machine

The first time you launch a newly installed Linux distribution, a console window will open and you'll be asked to wait for files to de-compress and be stored on your PC. All future launches should take less than a second.

You will then need to create a user account and password for your new Linux distribution.

CONGRATULATIONS! You've successfully installed and set up a Linux distribution that is completely integrated with your Windows operating system!

The --install command performs the following actions:

• Enables the optional WSL and Virtual Machine Platform components
• Downloads and installs the latest Linux kernel
• Sets WSL 2 as the default
• Downloads and installs a Linux distribution (reboot may be required)

By default, the installed Linux distribution will be Ubuntu. This can be changed using wsl --install -d <Distribution Name>. (Replacing <Distribution Name> with the name of your desired distribution.) Additional Linux distributions may be added to your machine after the initial install using the wsl --install -d <Distribution Name> command.

To see a list of available Linux distributions, enter wsl --list --online.

Manual Installation Steps

If you are not on a Windows Insiders build, the features required for WSL will need to be enabled manually following the steps below.

Step 1 - Enable the Windows Subsystem for Linux

You must first enable the 'Windows Subsystem for Linux' optional feature before installing any Linux distributions on Windows.

Open PowerShell as Administrator and run:

We recommend now moving on to step #2, updating to WSL 2, but if you wish to only install WSL 1, you can now restart your machine and move on to Step 6 - Install your Linux distribution of choice. To update to WSL 2, wait to restart your machine and move on to the next step.

Step 2 - Check requirements for running WSL 2

To update to WSL 2, you must be running Windows 10.

• For x64 systems: Version 1903 or higher, with Build 18362 or higher.
• For ARM64 systems: Version 2004 or higher, with Build 19041 or higher.
• Builds lower than 18362 do not support WSL 2. Use the Windows Update Assistant to update your version of Windows.

To check your version and build number, select Windows logo key + R, type winver, select OK. (Or enter the ver command in Windows Command Prompt). Update to the latest Windows version in the Settings menu.

Note

If you are running Windows 10 version 1903 or 1909, open 'Settings' from your Windows menu, navigate to 'Update & Security' and select 'Check for Updates'. Your Build number must be 18362.1049+ or 18363.1049+, with the minor build # over .1049. Read more: WSL 2 Support is coming to Windows 10 Versions 1903 and 1909. See the troubleshooting instructions.

Step 3 - Enable Virtual Machine feature

Before installing WSL 2, you must enable the Virtual Machine Platform optional feature. Your machine will require virtualization capabilities to use this feature.

Open PowerShell as Administrator and run:

Restart your machine to complete the WSL install and update to WSL 2.

Step 4 - Download the Linux kernel update package

1. Download the latest package:

   Note

   If you're using an ARM64 machine, please download the ARM64 package instead. If you're not sure what kind of machine you have, open Command Prompt or PowerShell and enter: systeminfo | find 'System Type'.

2. Run the update package downloaded in the previous step. (Double-click to run - you will be prompted for elevated permissions, select ‘yes’ to approve this installation.)

Once the installation is complete, move on to the next step - setting WSL 2 as your default version when installing new Linux distributions. (Skip this step if you want your new Linux installs to be set to WSL 1).

Note

For more information, read the article changes to updating the WSL2 Linux kernel, available on the Windows Command Line Blog.

Docker Windows 10 Home 1903

Step 5 - Set WSL 2 as your default version

Open PowerShell and run this command to set WSL 2 as the default version when installing a new Linux distribution:

Step 6 - Install your Linux distribution of choice

1. Open the Microsoft Store and select your favorite Linux distribution.

   The following links will open the Microsoft store page for each distribution:

2. From the distribution's page, select 'Get'.

The first time you launch a newly installed Linux distribution, a console window will open and you'll be asked to wait for a minute or two for files to de-compress and be stored on your PC. All future launches should take less than a second.

You will then need to create a user account and password for your new Linux distribution.

CONGRATULATIONS! You've successfully installed and set up a Linux distribution that is completely integrated with your Windows operating system!

Install Windows Terminal (optional)

Windows Terminal enables multiple tabs (quickly switch between multiple Linux command lines, Windows Command Prompt, PowerShell, Azure CLI, etc), create custom key bindings (shortcut keys for opening or closing tabs, copy+paste, etc.), use the search feature, and custom themes (color schemes, font styles and sizes, background image/blur/transparency). Learn more.

Install Windows Terminal.

Set your distribution version to WSL 1 or WSL 2

You can check the WSL version assigned to each of the Linux distributions you have installed by opening the PowerShell command line and entering the command (only available in Windows Build 18362 or higher): wsl -l -v

To set a distribution to be backed by either version of WSL please run:

Docker Windows 10 Home Hyper-v

Make sure to replace <distribution name> with the actual name of your distribution and <versionNumber> with the number '1' or '2'. You can change back to WSL 1 at anytime by running the same command as above but replacing the '2' with a '1'.

Note

The update from WSL 1 to WSL 2 may take several minutes to complete depending on the size of your targeted distribution. If you are running an older (legacy) installation of WSL 1 from Windows 10 Anniversary Update or Creators Update, you may encounter an update error. Follow these instructions to uninstall and remove any legacy distributions.

Docker Windows 10 Home Virtualbox

If wsl --set-default-version results as an invalid command, enter wsl --help. If the --set-default-version is not listed, it means that your OS doesn't support it and you need to update to version 1903, Build 18362 or higher.

If you see this message after running the command: WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel. You still need to install the MSI Linux kernel update package.

Additionally, if you want to make WSL 2 your default architecture you can do so with this command:

This will set the version of any new distribution installed to WSL 2.

Troubleshooting installation

Below are related errors and suggested fixes. Refer to the WSL troubleshooting page for other common errors and their solutions.

Docker Win10 Home Vs

• Installation failed with error 0x80070003

  • The Windows Subsystem for Linux only runs on your system drive (usually this is your C: drive). Make sure that distributions are stored on your system drive:
  • Open Settings -> **System --> Storage -> More Storage Settings: Change where new content is saved

• WslRegisterDistribution failed with error 0x8007019e

  • The Windows Subsystem for Linux optional component is not enabled:
  • Open Control Panel -> Programs and Features -> Turn Windows Feature on or off -> Check Windows Subsystem for Linux or using the PowerShell cmdlet mentioned at the beginning of this article.

• Installation failed with error 0x80070003 or error 0x80370102

  • Please make sure that virtualization is enabled inside of your computer's BIOS. The instructions on how to do this will vary from computer to computer, and will most likely be under CPU related options.

• Error when trying to upgrade: Invalid command line option: wsl --set-version Ubuntu 2

  • Enure that you have the Windows Subsystem for Linux enabled, and that you're using Windows Build version 18362 or higher. To enable WSL run this command in a PowerShell prompt with admin privileges: Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux.

• The requested operation could not be completed due to a virtual disk system limitation. Virtual hard disk files must be uncompressed and unencrypted and must not be sparse.

  • Deselect “Compress contents” (as well as “Encrypt contents” if that’s checked) by opening the profile folder for your Linux distribution. It should be located in a folder on your Windows file system, something like: USERPROFILE%AppDataLocalPackagesCanonicalGroupLimited...
  • In this Linux distro profile, there should be a LocalState folder. Right-click this folder to display a menu of options. Select Properties > Advanced and then ensure that the “Compress contents to save disk space” and “Encrypt contents to secure data” checkboxes are unselected (not checked). If you are asked whether to apply this to just to the current folder or to all subfolders and files, select “just this folder” because you are only clearing the compress flag. After this, the wsl --set-version command should work.

Docker Windows 10 Home Wsl

Note

In my case, the LocalState folder for my Ubuntu 18.04 distribution was located at C:Users<my-user-name>AppDataLocalPackagesCanonicalGroupLimited.Ubuntu18.04onWindows_79rhkp1fndgsc

Docker Windows 10 Home Wsl2

Check WSL Docs GitHub thread #4103 where this issue is being tracked for updated information.

• The term 'wsl' is not recognized as the name of a cmdlet, function, script file, or operable program.

  • Ensure that the Windows Subsystem for Linux Optional Component is installed. Additionally, if you are using an ARM64 device and running this command from PowerShell, you will receive this error. Instead run wsl.exe from PowerShell Core, or Command Prompt.

• Error: This update only applies to machines with the Windows Subsystem for Linux.

  • To install the Linux kernel update MSI package, WSL is required and should be enabled first. If it fails, it you will see the message: This update only applies to machines with the Windows Subsystem for Linux.
  • There are three possible reason you see this message:

  1. You are still in old version of Windows which doesn't support WSL 2. See step #2 for version requirements and links to update.

  2. WSL is not enabled. You will need to return to step #1 and ensure that the optional WSL feature is enabled on your machine.

  3. After you enabled WSL, a reboot is required for it to take effect, reboot your machine and try again.

• Error: WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel .

  • If the Linux kernel package is missing in the %SystemRoot%system32lxsstools folder, you will encounter this error. Resolve it by installing the Linux kernel update MSI package in step #4 of these installation instructions. You may need to uninstall the MSI from 'Add or Remove Programs', and install it again.