Build a Flutter App for Linux from a Windows Machine
Build a Flutter Linux app from a Windows machine using WSL, without installing two operating systems or buying two computers.
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.
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.
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).
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 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) 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: https://learn.microsoft.com/en-us/windows/wsl/install. 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.
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.
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.confto begin editing the relevant configuration file. Then, in this file, copy/paste the following two lines:
[interop]
appendWindowsPath = falseTo save the new configuration, press Ctrl + S. Finally, exit the file with Ctrl + X.
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 https://github.com/flutter/flutter.gitThe download may take a few moments depending upon your connection speed.
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"
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.
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.
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.
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.
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.
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.
From this point, you can distribute your new Linux app using whichever method you prefer.
Thanks very much for reading and happy Fluttering!
