What is %(source.dir) in Buildozer? Complete Guide for Beginners

When building Android apps using Python (Kivy/KivyMD) with Buildozer, you often edit the buildozer.spec file. This file controls your app’s configuration, such as name, package, permissions, and file paths.

One line you may see looks like this:

icon.filename = %(source.dir)s/data/icon.png

This raises an important question:

👉 What exactly is %(source.dir)?

🔑 What is %(source.dir)?

%(source.dir) is a variable (placeholder) used by Buildozer.

👉 It represents your project’s root directory
(the folder where buildozer.spec is located)

During the build process, Buildozer automatically replaces this variable with the full absolute path to your project.

⚙️ How it works

Example:

icon.filename = %(source.dir)s/data/icon.png

During build, this becomes something like:

/home/user/myapp/data/icon.png

🔍 Breakdown:

• %() → variable syntax
• source.dir → project root directory
• s → string formatting specifier (required)

📂 Example Project Structure

myapp/
├── buildozer.spec
├── main.py
└── data/
    └── icon.png

Using:

icon.filename = %(source.dir)s/data/icon.png

✔ Buildozer will correctly locate the file regardless of where the project is stored.

⭐ Why use %(source.dir)?

✔ Portable projects

You can move your project anywhere (Desktop → Documents → another PC) without breaking paths.

✔ No need for absolute paths

Avoid writing long paths like:

/home/user/Desktop/myapp/...

✔ Cleaner and safer configuration

Especially useful in larger or shared projects.

⚠️ Important Rules

✅ Correct syntax

%(source.dir)s

👉 The s at the end is REQUIRED

❌ Common mistakes

Missing s

%(source.dir)/data/icon.png

Wrong format

%source.dir/data/icon.png

✔ Correct

%(source.dir)s/data/icon.png

🔁 Simple Alternative

If your file is in the root folder:

icon.filename = icon.png

✔ This also works fine for small/simple projects.

🚀 Important Note

After changing any file path in buildozer.spec,  always rebuild:

buildozer android clean
buildozer android debug

👉 This ensures changes are properly applied.

🧾 Final Summary

• %(source.dir) = your project root directory
• Automatically replaced during build
• Makes your project portable, clean, and reliable
• Best practice for managing file paths in Buildozer

Using %(source.dir) correctly helps avoid path errors and keeps your project flexible across different systems.