Dfx on windows for beginners

this is a small video i made for beginners to get the sdk to run under windows. its the first time for me to do something like this so i would appreciate your feedback :slight_smile:
i know the audio is a bit off and the video is longer than necessary :smiley:
if you have topics you want to cover via video make sure to hit me up and ill add them to the mission control youtube channel!


this was great, nice tutorial @cryptoschindler


I use Windows 10 and you can do this without a VM.

Install Windows Subsystem Linux 2 Ubuntu:

Install Visual Studio 2 Insiders which allows you to code in your Windows 10 Environment to your Ubuntu Environment. VSCode Insiders is a different application then VSCode, so your default VSCode should remain unchanged.

  • Open a Command Prompt [Windows]
  • Type wsl and now you should be in the Ubuntu Terminal
  • Install Dfinity sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
    or follow https://sdk.dfinity.org/developers-guide/quickstart.html
  • cd into hello project.
  • type code . which should open a VS Insider window.
  • Open a new Terminal in VSCode Insiders and type dfx start
  • Open another Terminal and install/run hello project

Note: When you open a terminal within VSCode Insiders, it should be in the same path as your hello project.


oh wow, thanks for sharing this! sure makes things a lot easier :thinking:


Excellent video!

Virtualbox is still a good catch-all solution across all Windows versions.

Yes Windows 10 users can use WSL if they like. But depending on how frugal you are with updates you might not have it on Windows 10 Home yet.

Some might like being able to dump a VM and start again too.


Great guide. VSCode might have WSL integration in the main release now, so you may not need the insider build? Worth a check.


Good conversation to start.


Epic tutorial!!! Thanks for sharing @cryptoschindler


Thanks, Moritz :wave: You definitely have YouTube blogger skills :+1: Nice English and explanation of SDK running.


Ok, so the main release of VSCode lets you do this now too (you might need to close VSCode after the first run and then run code . again). So thanks Rick, between these two guides all Windows devs should be covered.

You’ll know you’re connected when you can see WSL at the bottom left of the VSCode application window. You can always start and manage WSL connections from here too.


Thanks for your contributions @cryptoschindler


if you dont want to go through the installation process of the virtual machine, you can just download a virtualbox image instead!

check out this very handy project :slight_smile:

make sure to read their FAQ for the username and password of the installation!


A very clear step by step guide to getting Windows Subsystem for Linux set up and connected to VSCode (you can skip the python bit in the middle):


So for new readers here, there are 2 good options for Windows users:

  • Installing Ubuntu on a VM using VirtualBox (all Windows versions).
  • Installing Windows Subsystem for Linux and connecting to it with VSCode (Windows 10).

You can then install the DFINITY Canister SDK on the command line (terminal) in either of these.


You might be getting errors with canister installs on WSL version 1 (the current non-insider build). It seems that the VSCode WSL server holds onto files while open. Killing the server frees the files up and canister installs run fine then, you can do this by closing the WSL connection from the bottom left of VSCode.

WSL v2 is in the next public Windows 10 build, expected in the next few weeks, which hopefully should resolve this.


This is also possible to create dfx docker container and use it everywhere you need.

  1. Download dfx’s install.sh
  2. Remove or comment these lines from it (explained below):
    #need_cmd sudo
    #if ! confirm_license; then
    #    echo "Please accept the license to continue."
    #    exit
  1. Make a Dockerfile with something like this:
FROM ubuntu:18.04

RUN apt-get update
RUN apt-get install curl -y

COPY install.sh install.sh
RUN sh install.sh

WORKDIR /root/dfx
ENTRYPOINT ["/usr/local/bin/dfx"]
  1. Then just use docker run with correct mounting

Unfortunately, to make it work, we should remove lines responsible for showing the license agreement, which we are not allowed to remove legally. So please, don’t use this method unless you know what are you doing. Why should we remove these lines? Because the agreement is interactive but docker doesn’t support interactive build. So we are absolutely not allowed to share a docker image like this.
Maybe, it is possible to make legally correct docker image by including licence agreement process into Dockerfile itself (each time you run the container you should accept the agreement). This approach makes the license agreement a little annoying, but let’s anyone use dfx under any system supporting docker and also keeps it’s legal strength IMO.

I’m not a lawyer, just saying that from technical point of view this can be achieved easily.


I’m ready to start learning!


The latest public Windows 10 release resolves this (version 2004) by supporting WSL v2.

A guide to installing WSL v2 is here: https://docs.microsoft.com/en-us/windows/wsl/install-win10


Thank you, it was really useful! :slight_smile:

1 Like