As a Flutter dev, you might come across a situation where you need to modify and Debug Native iOS and Android plugins in Flutter. Maybe there’s a behavior or a bug in a plugin you’re using, and you want to modify or fix it. Flutter is very robust, and compared with MAUI and Xamarin, I’ve rarely needed to access native code. Today, I’ll take you through debugging and modifying a popular plugin’s iOS and Android code right from a Flutter app.

To be honest, when I started with Flutter, I dreaded the moment when I’d be forced to get into the native code in Flutter. Because It would require me to get my hands into Objective-C/Swift. Kotlin/Java are not strange to me, since I started as an Android dev, and they’re similar to C#. One of the few advantages Xamarin/MAUI has over Flutter is the fact that your native code is in one programming language (C#), and you don’t have to switch between IDEs and Operating systems all the time. But hey! I found out that it was far more easy in Flutter than what I expected.

If you find this article useful, please follow me on Twitter,  Github, Linkedin, or like my Facebook page to stay updated.
Follow me on social media and stay updated

The Problem

In a project I was working on, I had to integrate a robust PDF reader into the App I was building. We choose PSPDFKit. Though this library is robust and does a good job of displaying PDFs, we needed to extend its functionalities. For example, we needed to listen to page changes (when a user swipes to a new page in the PDF reader), get the number of pages the PDF is made of, etc. In addition to that, there were a few bugs we came across when using this library with other plugins like just_audio and Firebase messaging. To get this done, I had to add new features and correct the bugs. As you guessed, I had to get my hands into native code (Objective C, Kotlin, java, swift).

Modify and Debug Native iOS and Android plugins in Flutter Apps

To understand this easily, we have to go from first principles. A plugin in your Flutter app, is just a dart package, with the shared dart code, and the iOS and Android code bases. So, to modify/debug the plugin, you will need full control over the Dart code, the Android code, and the iOS code. Here are the steps to follow. NOTE: In my case (as in the majority of cases), the source code of the plugin was available on GitHub.

1- Reference your plugin directly from its source code

  • Download the plugin’s source code.
  • Place the source code in the same directory as that of your project.
  • In your pubspec.yaml, instead of referencing the pub package, reference the raw code. Here is an example:
  • Clean your project with flutter clean
  • Re-install the packages flutter packages get
  • Make sure you build and run the project
  • You’ll be able to place breakpoints in the plugin’s dart code and debug it.

2- Debugging the iOS native code

  • After building and running the app, stop it. (NOTE: You should be on MacOS now)
  • Go to your project’s ios directory
  • Open the Runner.xcworkspace file in XCode

At this point, the next step will be to enter into the Objective-C or swift source code, debug (breakpoints, log messages), modify, and add features to the library. You might have never written a swift or Objective-C code in your life, but you can ask questions to ChatGPT.

  • Since we have the plugin’s native iOS code downloaded, we can modify it directly. In my case, the library was PSPDFKit To access this code from X-Code, go to the Development pods:
Debug Native iOS plugins in Flutter
Debug Native iOS plugins in Flutter
Debug Native iOS plugins in Flutter
Debug Native iOS plugins in Flutter

I advise you to read the plugin’s documentation so that you know what you’re doing when modifying the native code. Once you’re done modifying and placing breakpoints, just press the run button on Xcode, and check the outcome.

3- Debugging the Android native code

On Android, it’s very similar to iOS. But, you’ll have to package your project in other to place breakpoints.

  • Package your project with the command: flutter build apk
  • Open the Android folder of your Flutter project directly in Android studio
  • Open your package, and navigate through the source code. Place breakpoints where required. As shown below
Debug Native Android plugins in Flutter
Debug Native Android plugins in Flutter

NOTE: If like me, you’re impatient and don’t want to package an apk all the time, what you can do, is open your Android project in Android Studio, open the Kotlin/java files from the plugin’s directory (navigate to the directory. Or, in VScode, deliberately place an error in the Kotlin file, and run the project in Android Studio. The project will not run, and display an error in the file concerned. Just double-click on the file in the error window and open it, then modify it). Once you modify it in Android Studio, place Log messages to debug, since you won’t be able to place breakpoints on the files outside the package.


I hope this tutorial demystified the process of debugging native plugins in your Flutter app. If you want to improve or debug a native plugin, use this article to guide you. If you liked this tutorial, please share it, and like it. It means a lot to me. Thank you.

Follow me on social media and stay updated

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.