11/21/23, 3:20 PM
Build a Flutter App for Linux from a Windows Machine | by Scott Hatfield | Medium
Build a Flutter App for Linux from a Windows Machine
medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
Scott Hatfield
October 11, 2022
Build a Flutter Linux app from a Windows machine using WSL,
without installing two operating systems or buying two
computers.
Scott Hatfield
A Different Platform for Each Build Target
🔨
One of the greatest parts of developing Flutter apps is the ability for the framework to
create builds for many different platforms from a single codebase. Flutter officially
supports Android, iOS, Linux, macOS, and web apps. With a little tinkering and the help
of some Flutter plugins, you can even produce builds for Wear OS and other Android-like
platforms.
However, the big catch with Flutter’s cross-platform build abilities is that, in most cases,
you will need a specific development setup for each target platform. Flutter’s build system
uses platform-specific features to produce installers/packages so if, for example, you
want to create a Windows app, you will need a machine running Windows to do it.
Likewise, creating iOS or macOS apps requires a machine running macOS. Building apps
for Linux, including Linux running on Raspberry Pis requires a Linux machine.
Different Flutter build targets require different development platforms.
While this last platform, Linux, is likely not the most popular target for Flutter apps, it
might be the most demanding in terms of the required development setup. Windows and
macOS machines are, of course, very common among developers, but Linux
development setups are much less commonly used with only 13% of developers working
on Linux machines.
https://medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
1/10
11/21/23, 3:20 PM
Build a Flutter App for Linux from a Windows Machine | by Scott Hatfield | Medium
Building on the Wrong Platform
⚠️
So, how does the requirement to build Flutter apps for specific targets manifest in real
life? Well, if you try to run a flutter build ___ command for a target platform that your
operating system does not support, the Flutter SDK will give you an error. For example,
the screenshot below shows the error that results from attempting to build a Linux app on
a Windows machine (at least without using the method described in this article).
The Flutter SDK will normally deliver an error when attempting to build a Linux app on Windows.
Method Overview
🚀
While you could certainly dual boot either a Windows or a macOS machine by installing
Linux alongside the default operating system, this process does involve quite a bit of
complexity and storage space. Also, a dual boot setup is a bit like having two different
computers, and that comes with a number of inconveniences when it comes to sharing
tools and files. Last, if you do Flutter development for your employer, your IT department
might not be too keen on dual boot setups.
Well, if you are using a Windows computer for Flutter development (and according to the
chart above, about 60% of you will be) then you can actually build Flutter apps for Linux
from right within your existing setup without any dual booting, third-party software
https://medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
2/10
11/21/23, 3:20 PM
Build a Flutter App for Linux from a Windows Machine | by Scott Hatfield | Medium
installation, or CI/CD Pipeline subscriptions. To build a Linux app from Flutter code on
Windows, we will use the Linux Subsystem for Windows, introduced in Windows 10.
Windows Subsystem for Linux (WSL) allows you to run a Linux terminal directly
inside Windows.
Windows Subsystem for Linux (WSL) is a tool in Windows 10 and 11 that allows you to
run a Linux file system and Linux command-line tools directly within Windows. It is a bit
like having a terminal instance that uses Linux rather than Command Prompt or
PowerShell.
Prerequisites
👌
Before we dive into the tutorial portion of this article, there are a few items that yo should
have set up already:
You will need Windows Subsystem for Linux set up on your machine. Microsoft has
documentation on their website: . While you could use other Linux distros, this
tutorial assumes you are using Ubuntu.
You will need administrator permissions on your machine as we will be running quite
a few commands with sudo , which requires elevated privileges.
This documentation is written on a Windows machine running Windows 11.
However, these instructions should work the same way on Windows 10.
https://medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
3/10
11/21/23, 3:20 PM
Build a Flutter App for Linux from a Windows Machine | by Scott Hatfield | Medium
Build a Flutter app in WSL
Let’s get down to brass tacks and cover the method used to build Linux apps on Windows
using Linux Subsystem for Windows. This will essentially involve a series of commands
entered into the WSL Ubuntu terminal.
1. Use a Different PATH with WSL
We are going to jump straight in with a bit of a complicated first step. The thing to
understand about WSL is that it does not function as a separate, standalone Linux
instance on your Windows machine. It is a subsystem, meaning that your WSL terminal
operates inside your Windows installation. By default, when you enter a command into
the Ubuntu terminal window, it will reference the PATH of your Windows installation.
However, this is a problem for running Flutter commands because this means that your
Flutter commands in the WSL terminal will result in errors because the Flutter SDK
referenced by the PATH on your Windows computer uses files with Windows formatting
features. Essentially, Linux does not understand the Windows version of the Flutter
SDK.
This error results from running Flutter commands in WSL when it uses the Windows PATH.
The 'bash\r': No such file or directory error there results from the Flutter SDK file
containing Windows-style line endings, that Linux does not understand. Windows uses
\r\n line endings while Linux uses \n line endings. So that error is referencing the
carriage return ( \r ) character used in Windows.
Anyway, let’s fix this problem. To avoid this error, we will modify a WSL configuration file
to make WSL use its own PATH variable rather than the Windows one. So, in the Ubuntu
terminal, enter the command
sudo nano /etc/wsl.conf
https://medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
4/10
11/21/23, 3:20 PM
Build a Flutter App for Linux from a Windows Machine | by Scott Hatfield | Medium
to begin editing the relevant configuration file. Then, in this file, copy/paste the following
two lines:
[interop]appendWindowsPath = false
To save the new configuration, press Ctrl + S. Finally, exit the file with Ctrl + X.
Enter the lines shown in this screenshot into the wsl.conf file.
Last, we will need to close the WSL window and restart it for the new configuration file to
take effect. To close the WSL terminal, switch over to your Windows terminal program of
choice and enter the command, wsl --shutdown . Then, just open WSL again by
launching the Ubuntu program.
2. Clone the Flutter SDK from GitHub
Now that we have the PATH set up for success (but not working quite yet) we can move
on to something easier. Flutter’s documentation describes a number of ways to install the
Flutter SDK in Ubuntu. However, for various reasons the easiest one to use with WSL is
to clone the Flutter SDK from GitHub. This is the process discussed in the “Install Flutter
manually” section of the documentation.
In your WSL terminal window, enter the command to clone the Flutter SDK repository:
git clone
The download may take a few moments depending upon your connection speed.
https://medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
5/10
11/21/23, 3:20 PM
Build a Flutter App for Linux from a Windows Machine | by Scott Hatfield | Medium
Clone the Flutter SDK from GitHub.
3. Add Flutter to the WSL PATH
Remember before when we set up WSL to use a different PATH than the Windows
system? Well now we need to add the newly downloaded Flutter SDK to the PATH in
WSL. There are two ways to make this change. The first is temporary and the second is
permanent. We will be using the permanent method so that this step does not need to be
re-done each time WSL is launched.
So, in the WSL terminal, enter the command,
export PATH"$PATH:flutter/bin"
Add the location of the Flutter SDK clone to the PATH.
4. Run Flutter Doctor
Everything should be ready to perform Flutter Linux builds now. But, just to make sure
nothing is missing, it is probably a good idea to run a flutter doctor command. This will
actually accomplish two things. First, the system will download the Dart SDK. Second, of
course, the Flutter doctor command will run and let you know about any issues in your
setup.
https://medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
6/10
11/21/23, 3:20 PM
Build a Flutter App for Linux from a Windows Machine | by Scott Hatfield | Medium
Run the “flutter doctor” command to both install the Dart SDK and get the Flutter Doctor output.
For the purposes of this article, the main points we care about are the top one about
Flutter being set up and the one declaring “Linux toolchain — develop for Linux desktop.”
As long as these two items are checked off, we can proceed to the next step.
If, however, the tool lists any dependencies required for Flutter to work correctly, go
ahead and install those.
5. Clone or Copy your Project
The final requirement before the Linux app can be built is that your Flutter project needs
to be in the WSL file system so it can be the target of the build command. There are two
good ways of getting your project into the WSL file system: cloning your project from your
version control repository or copying your project from the Windows file system to the
WSL file system.
Clone from Version Control
The first of these two methods is the easiest. If you already have your project in a version
control system, you can simply clone your project into the WSL file system. Just use a
standard Git command like the one we used earlier to clone the Flutter SDK.
In this example, we will be using the Flutter Gallery sample app.
https://medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
7/10
11/21/23, 3:20 PM
Build a Flutter App for Linux from a Windows Machine | by Scott Hatfield | Medium
One method to load your project into the WSL file system is to clone it from version control.
Copy from the Windows File system
In case you don’t want to clone your project from version control, or perhaps because you
would like to test your Linux build before committing changes into version control, another
method to load your project into the WSL file system is to copy it from the Windows file
system.
First a bit of background information. As we discussed before, WSL runs inside your
normal Windows installation. Therefore, the WSL terminal has access to your Windows
files. This can be accomplished because your Windows file system is a mounted drive
inside WSL. If you enter the command, cd /mnt/c you will end up in your Windows C:
drive.
So, to copy your Flutter project from the Windows file system to the Linux file system in
WSL, use the following command format:
cp -r /mnt/c/<path to your project> .
Note that the -r flag in this command stands for “recursive.” This means that the copy
command will copy the specified directory plus any child directories, and any children of
the children, and so on. The period at the end of the command just makes Linux copy the
target file into the current directory.
Command to copy the Flutter project from the Windows file system to the Linux file system.
https://medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
8/10
11/21/23, 3:20 PM
Build a Flutter App for Linux from a Windows Machine | by Scott Hatfield | Medium
6. Create your Flutter Linux App
And now the moment of truth has finally arrived. It is time to build a Flutter app for Linux
on a Windows machine.
Building a Flutter Linux app on a Windows computer.
To create the Flutter build, first navigate into the root directory of your project. Then, enter
the command, flutter build linux. After that, it is just a matter of waiting for a new
moments for your shiny new Linux app to be complete.
Once it is done building, you can find the application in the build directory inside your
Flutter project.
The finished Linux build can be found in the build directory of your Flutter project.
Parting Thoughts
🏁
In many cases, any particular development environment can only be used to build Flutter
apps for specific operating systems. Windows cannot normally be used to build Flutter
apps for Linux. However, using Microsoft’s Linux Subsystem for Linux, we were able to
build a Flutter Linux app from within WSL.
https://medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
9/10
11/21/23, 3:20 PM
Build a Flutter App for Linux from a Windows Machine | by Scott Hatfield | Medium
From this point, you can distribute your new Linux app using whichever method you
prefer.
Thanks very much for reading and happy Fluttering!
https://medium.com/@Toglefritz/build-a-flutter-app-for-linux-from-a-windows-machine-4ca3f69e303d
10/10