Blog Post

Run a Flutter App on an Emulator inside Docker

Illustration: Run a Flutter App on an Emulator inside Docker

When building Continuous Integration (CI), you might find yourself needing to run your application on an emulator in use cases such as automated UI testing or generating screenshots. In this blog post, I’ll walk you through how to easily dockerize your Flutter application and run it on a dockerized Android emulator.

We’ll start by creating a new Flutter project, so make sure you have the Flutter environment set up with the latest version of Flutter. You can check your setup by running flutter doctor, which gives you information about which version of Flutter is installed and how to update it if it isn’t the latest.

Go to your terminal at any desired location and run flutter create mydockerisedapp to create a new Flutter application. You can also use File > New > New Flutter Project… in Android Studio, or use Visual Studio Code to create a new Flutter project.

This setup will require two Docker containers: one to run the application, and another for the Android emulator.

Flutter Docker Image

First, set up the Flutter application Dockerfile, which contains the setup instructions for our Flutter Docker image:

FROM ubuntu:20.04

ENV DEBIAN_FRONTEND="noninteractive"
ENV ANDROID_SDK_ROOT="/usr/local/android-sdk"
ENV GRADLE_USER_HOME="/opt/gradle"
ENV FLUTTER_ROOT="/opt/flutter"
ENV PATH="$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$ANDROID_SDK_ROOT/emulator:$ANDROID_SDK_ROOT/platform-tools:$ANDROID_SDK_ROOT/platforms:$FLUTTER_ROOT/bin:$GRADLE_USER_HOME/bin:$PATH"

# Install the necessary dependencies.
RUN apt-get update \
  && apt-get install --yes --no-install-recommends \
    openjdk-$JAVA_VERSION-jdk \
    curl \
    unzip \
    sed \
    git \
    bash \
    xz-utils \
    libglvnd0 \
    ssh \
    xauth \
    x11-xserver-utils \
    libpulse0 \
    libxcomposite1 \
    libgl1-mesa-glx \
  && rm -rf /var/lib/{apt,dpkg,cache,log}

# Install Gradle.
RUN curl -L $GRADLE_URL -o gradle-$ \
  && apt-get install -y unzip \
  && unzip gradle-$ \
  && rm gradle-$

# Install the Android SDK.
RUN mkdir /root/.android \
  && touch /root/.android/repositories.cfg \
  && mkdir -p $ANDROID_SDK_ROOT \
  && curl -o $ANDROID_TOOLS_URL \
  && unzip -qq -d "$ANDROID_SDK_ROOT" \
  && rm \
  && mv $ANDROID_SDK_ROOT/cmdline-tools $ANDROID_SDK_ROOT/latest \
  && mkdir -p $ANDROID_SDK_ROOT/cmdline-tools \
  && mv $ANDROID_SDK_ROOT/latest $ANDROID_SDK_ROOT/cmdline-tools/latest \
  && yes "y" | sdkmanager "build-tools;$ANDROID_BUILD_TOOLS_VERSION" \
  && yes "y" | sdkmanager "platforms;android-$ANDROID_VERSION" \
  && yes "y" | sdkmanager "platform-tools"

# Install Flutter.
RUN curl -o flutter.tar.xz $FLUTTER_URL \
  && mkdir -p $FLUTTER_ROOT \
  && tar xf flutter.tar.xz -C /opt/ \
  && rm flutter.tar.xz \
  && git config --global --add /opt/flutter \
  && flutter config --no-analytics \
  && flutter precache \
  && yes "y" | flutter doctor --android-licenses \
  && flutter doctor \
  && flutter update-packages

Now, your Dockerfile is set up.


For the emulator, we’ll use an open source emulator image provided by Google. This will run as a separate Docker container, and we’ll connect to it from our Flutter application over a Docker network using adb.

ℹ️ Note: This setup requires KVM, which is only available on Linux (Ubuntu and Debian), and therefore won’t work on Mac and Windows machines.

Docker Compose

Next, we’ll set up a docker-compose.yml file to run the containers together:

version: '3.6'

         context: '.'
         dockerfile: Dockerfile
      image: 'flutter'
      working_dir: 'app'
         - emulator
         - './:./app'

         - 8554/tcp
         - 5555/tcp
         - '/dev/kvm:/dev/kvm'
         - .env

As you might notice, the Flutter application app depends on the emulator service, and they’re linked by a Docker network. There’s no need to define any networks, because Docker Compose will automatically create a default network.

Bash Script

Lastly, we’ll set up the script with the commands needed to run the application:


# Connect to the Android emulator container.
adb connect emulator:5555

#List the available Flutter devices. You should see the connected dockerized emulator.
flutter devices

# Install the Flutter packages.
flutter pub get

# Run the Flutter app on the connected emulator.
# Add `--trace-startup` to stop the Flutter process from blocking the terminal.
flutter run --trace-startup

mkdir -p 'screenshots' || exit 1

# Take a screenshot of the Flutter app.
adb shell screencap /sdcard/screenshot.png

adb pull /sdcard/screenshot.png screenshots/flutter-screen.png

Now, add execute permissions to by running chmod +x

Running the Application

Finally, run the application as shown in the script below:

$ docker compose run app

This will set up the Docker containers and execute inside the app container. Wait for the execution to complete, and you’ll see the flutter-screen.png image file in the screenshots folder.


In this blog post, we looked at how to run a dockerized Flutter application on a dockerized Android emulator. The setup can be used for purposes such as automated UI testing and automatically generating screenshots.

Julius Kato Mutumba Native Engineer

Julius joined PSPDFKit in 2021 as an Android engineer and is now the Cross-Platform Team Lead. He has a passion for exploring new technologies and solving everyday problems. His daily tools are Dart and Flutter, which he finds fascinating. Outside of work, he enjoys movies, running, and weightlifting.

Related Products
PSPDFKit for Flutter

Product Page
Example Projects

Share Post
Free 60-Day Trial Try PSPDFKit in your app today.
Free Trial

Related Articles

Explore more
DEVELOPMENT  |  iOS • Android • Room • Kotlin Multiplatform • Tips

Seamless Room Database Integration for Kotlin Multiplatform Projects

PRODUCTS  |  Android • Releases

Android 2024.1 Update: Advanced Content Editing and Digital Signatures, Plus Expanded Jetpack Compose Support

TUTORIALS  |  Android • How To

How to Persist Zoom While Scrolling through a Document Using the PSPDFKit Android Library