duck-native 1.0.0

📖 What is Duck Native?

You already have a web app built with Duck Framework. Duck Native wraps it in an Android app, so people can install it from an APK or the Play Store like any other app.

You do not need to write Kotlin or Java. You edit one Python file (native/config.py) and run one command.

📚 New here? Read the guides: 📱 Native Actions (use the phone's features from your pages), 🧩 Native Widgets (use real Android widgets from Python, like a date picker or bottom sheet), 📦 Installing Dependencies (set up Gradle and Kotlin with duck sync) and 🤖 Building on Termux (build apps right on your phone).

📋 Table of contents

1. What you need
2. Install and Setup
3. Quick start
4. Guides
5. Commands
6. Settings
7. Where is my app?
8. Troubleshooting
9. Contributing

✅ What you need

💡 Just want to try your app on a phone quickly? Skip the last three rows and use duck native apk.

📦 Need Gradle or Kotlin? Run duck sync --with-dev, see Installing Dependencies.

🤖 Developing on a phone? Follow the Termux guide.

📦 Install and Setup

pip install duck-native

Apply settings

You must enable native in your settings file:

NATIVE_ENABLED = True

The above line enable Native capabilities for your app and it requires duck-native to be installed.

🚀 Quick start

Run these inside your Duck project folder.

1. Create the config

duck native init

This creates native/config.py.

2. Edit it

Open native/config.py and change at least these two lines:

APP_NAME = "My Duck App"
PACKAGE_NAME = "com.yourname.myapp"

3. Build

duck native build

4. Install the app

Copy build/app-debug.apk to your phone and open it, or plug your phone in and run adb install -r build/app-debug.apk.

That's it! 🎉

📚 Guides

🧰 Commands

duck native and duck-native are the same command. We suggest duck native as the base command, and the examples here use it. Use duck-native if you prefer one word, or python -m duck_native.

Every command takes an optional project folder, for example duck native build ../my-app.

⚡ Get a ready-made debug APK

duck native apk              # copies app-debug.apk into your build folder
duck native apk --install    # also installs it on a connected phone
duck native apk --output ~/Desktop/test.apk

This APK is the same for everyone, so settings like the app name, icon and permissions are not applied. Use duck native build when you need them.

🔨 What build does

You will see each step in the terminal:

1. Prepare: copies the Android project into build/android.
2. Generate: creates your icons, splash screen and manifest.
3. Build: runs Gradle on the copy.
4. Collect: copies the finished APK or AAB into build/.

If the build fails, Duck Native prints suggestions based on the error.

⚙️ Settings

All settings live in native/config.py. The common ones:

The generated file has a comment above every setting explaining it.

📁 Where is my app?

Everything ends up in the build/ folder of your project:

build/
├── app-debug.apk      ← debug build
├── app-release.aab    ← release bundle (Play Store)
├── android/           ← working copy of the Android project
└── generated/         ← icons, splash and manifest made for you

🩹 Troubleshooting

Still stuck? Open an issue and paste the output of the failed command.

🤝 Contributing

Contributions are welcome! See the contribution guide or open an issue.

📄 License

Released under the BSD 3-Clause License.