Usage update: in October 2024, the Pydroid 3 app's version 7.4 has finally gained Android's All Files Access permission. By granting this on first file access in the app, you may again download, unzip, and run the programs here anywhere in shared (a.k.a. internal) storage on your device. Likewise, your content files—including calendars in Frigcal and text and code in PyEdit—may be kept anywhere in shared storage and freely accessed there by other apps. This reverses a 2023 change in the app's version 6 that radically reduced program functionality, though the app still does not provide access to removable drives that are accessible with the new permission, oddly. For more info, see this page.
| Version: | June 8, 2019 (last revised Dec-2024) |
| Author: | © 2019-2024 M. Lutz, learning-python.com |
| Quick links: | View and
fetch this guide's media |
| View the related Mergeall doc |
This document describes how to run tkinter GUI programs on Android in the Pydroid 3 app's IDE (its edit+run GUI). This app recently added fledgling but astonishing tkinter support, which allows many Python 3.X programs with tkinter GUIs to be run in source-code form on smartphones, with no or minimal changes. The focus here is on using this app to run both the complete application programs at this site as well as the tutorial examples in the book Programming Python, 4th Edition (a.k.a. PP4E), but this coverage should apply to tkinter GUIs on Android devices in general.
Please note: the programs described here are wholly dependent on five other systems—Android, vendor extensions, Python, Android Tk, and Pydroid 3—all of which regularly change their behavior for both better and worse. Undocumented changes in Pydroid 3, for example, recently forced patches here and here, and Android currently threatens a much broader sea change. It's difficult for documentation to remain current in this context and just as tough for programs to continue working as intended.
While this guide presents potentially useful information and software that hope to be updated periodically, its content should be taken as a point-in-time snapshot. As usual, you should judge platform viability for yourself in whatever reality has bubbled up from a stew of morphing systems by the time you read these words.
Android 11 Happens
And bubbled it has: initial testing of Android 11 in early January 2021 regrettably suggests that some of the programs noted in this guide may be partly or wholly unusable on this Android today, though this story may improve over time with app and vendor fixes. Please see the off-page update here for details, and consider postponing an Android 11 install on your phone until its full implications for the programs you use are clearer.
Mergeall users: you probably cannot use the Mergeall GUI described here for syncs on Android 11 and later, because this platform revokes direct USB access for POSIX programs coded in Python, and microSD cards are increasingly rare. See the update on the original Mergeall scripts' page for more info; the interim Android Deltas Sync non-GUI alternative for performing syncs on later Androids (and more); and the standalone-app update below for a later solution. Other GUIs on this page are not harmed as badly by 11's changes.
And So Does Android 12
Late in 2021, Android 12 introduced a "phantom process killer" which starts terminating
child processes at arbitrary points after 32 are running. This has the
potential to impact Python programs of all sorts, including tkinter
GUIs. The impact can be mitigated by a new Developer feature flag or
adb command in
Android 12L and 13, and depends on how you use your phone; a Fold3,
for example, has not triggered a single process kill in one year of usage
(and a 12L Fold4 is faring the same).
See the full details
here.
Update: as of 2024 and Android 14, Samsung phones (and possibly others) now have a "Disable child process restrictions" setting in Developer options, which avoids phantom process kills when toggled on. This is welcome news and helpful for those technically savvy enough to enable and use Developer options but is naturally still subpar for apps and programs with more varied user bases. More info.
As of May 2023, the new Kivy/buildozer Android app PC-Phone USB Sync largely replaces the former Mergeall tkinter GUI described ahead. Unlike source code run in Pydroid 3's IDE (until its 2024 fix), the new standalone app is able to use All Files Access permission to process content on removable USB drives; retains the shared-storage access revoked later by Pydroid 3's version 6; skirts process culls with foreground services; and provides a much more seamless and paradigmatic Android user experience while also running on PCs.
For info on the new app, please see its separate website, as well as coverage on pages like this and this. Such apps must also use Kivy or other toolkits to build their GUIs because there is no support for tkinter-based apps today, but this is nevertheless recommended for new Python development on Android. Running code in Pydroid 3 may suffice for learning Python basics sans a PC, but little else.
See also the later 2026 Frigcal standalone app, which uses the Android storage picker to gain access to a calendars folder and similarly runs on both Android and PCs.
Before jumping into specific programs, here are a few administrative and global notes up front:
Findings here reflect versions 2.22 and 3.0 of Pydroid 3; 3.6 and 3.7 of Python; 7, 8, and 9 of Android (Nougat, Oreo, and Pie); and 8.6 of the Tk library wrapped by tkinter (in an Android port of unknown origin). Programs described here are currently known to work on all these systems, except where noted ahead. Per the notebox above, be sure to check facts here against these systems' current status if you're reading this in the future.
Suggestions for Pydroid 3 fullscreen and maximized viewing modes vary per program ahead. In general, fullscreen mode saves space but may conflict with Android's status-bar pulldown at display top; maximized mode uses space well but works only for GUIs without persistent popup window and with either explicit exit widgets or no need to process or verify exits (Pydroid 3 double-back exits do not run program exit handlers).
More on Fitting tkinter GUIs to Your Display
(Added fall 2020) Like most Android apps, the programs described on this page are sensitive to Android font-size, screen-zoom, and display-resolution settings and specs, and may vary in appearance and fit across devices. If parts of a GUI are clipped or offscreen on your display, try these options to see more content:
Pydroid 3's options at the top of this list are among the easiest solutions. They're all accessed by opening the app's top-left-corner pulldown, selecting "Settings," and tapping "System." They're also largely undocumented and come with tradeoffs and merit a few extra words here:
Downsides: you'll need to access the status bar manually if needed while using the GUI, and a GUI's window border can interfere with a pulled-down status bar when both are present at the top of the display.
Downsides: this mode works well for GUIs that follow the one-window-at-a-time paradigm of Android apps but makes it difficult—or impossible—to use desktop-metaphor GUIs with multiple persistent windows. Perhaps worse, this mode omits window-border titles and exit buttons that may be useful or required in some GUIs; Pydroid 3's double-back exit provides an alternative to window-border exit, but it may skip crucial tkinter exit handlers that finalize changed content (and is now single-back exit in Pydroid 3 4.X on some devices, oddly; more details here).
Downsides: at very-low DPI values, some widgets may be too small to see or use. Moreover, the available DPI values seem too sparse; you can't pick one between those offered, even if it may work better.
You may not prefer the results of some Pydroid 3 settings, and some may not work for specific GUIs (e.g., maximizing the first window hides the window-border exit button needed to save Frigcal changes). Tweak as desired for your GUIs and devices.
Example: a Galaxy Note20 Ultra's 120Hz screen required a lower resolution setting, which in turn made all tkinter GUIs larger and pushed one dialog's text partly off-screen. A lower Pydroid 3 screen-DPI setting of 320 improved size and fit, fixed the dialog, and roughly matched higher-resolution appearance at "Auto" DPI. See the effects of DPI and font settings on GUIs and dialogs for yourself in the captures gallery here.
Most of the tutorial-level tkinter GUI examples in the book Programming Python, 4th Edition work unchanged in Pydroid 3. True to its educational focus, this makes Pydroid 3 viable as a platform for working along with the book's presentation.
Here's a sample of the book's programs running on Android in Pydroid 3:
You can also view these screenshots in slideshow mode starting here.
Most of these examples yield smaller displays, which need not use tkinter fullscreen or maximized modes in Pydroid 3, but experiment with screen modes and phone orientations for best effect. Note that double-back exits in any viewing mode do not run tkinter exit handlers, and rotating the screen after a GUI is running may not work on some devices per usage notes ahead.
PP4E-Examples-1.4/Examples/PP4E/Gui
But navigate the examples-package tree to find additional tkinter code to run. Naturally, only this last step must be repeated whenever you wish to run an example.
Also keep the following in mind when using PP4E book examples on Android:
Gui folder.
Shortcuts look like
this or
this
and can be made by multiple Android file explorers including the app
here,
but be sure to set the default app or command to Pydroid 3.
Tip: uncheck "Parameters" when making shortcuts in Total Commander 3.0
(details).
On some devices, Pydroid 3 either kills the GUI silently or hangs altogether if the screen is rotated between portrait and landscape orientations while a tkinter GUI is running. Per details here, rotations are known to fail on multiple Samsung devices, but the latest of these rotate correctly if they avoid the Small screen-zoom display setting. If your rotates don't work, change your screen zoom to Medium or Large, apply system updates, or don't rotate.
In the same department as the preceding note: per here, changing phone orientation during a spawned activity (e.g., a Share or program-help browse) may cause the GUI to slide off screen or similarly hang, even on devices that handle rotations in general. Rotate twice to restore the GUI where supported.
sys.path list at the start of examples' code.
Use the unzipped examples folder's path up to and including its
Examples folder. For example, after an import sys:
sys.path.append('/sdcard/Download/PP4E-Examples-1.4/Examples')
pip install Pillow command line in Pydroid 3's
Terminal, or use the app's Pip interface. Both can be found in the
app's main (top left) menu. Pillow subsumes PIL and generally
requires no code changes in book examples.
helvetica,
but its other font limitations described here are still present.
Because some font types cause tkinter GUIs to crash silently in Pydroid 3,
examples that use custom text fonts may require code changes.
In general, font families courier,
times, and helvetica work (and monaco is
courier and arial is helvetica), but most
others crash the GUI, and italic and bold styles are ignored for courier.
sys.executable and
webbrowser spawning workarounds described
here).
On the other hand, changing code is a normal part of the book's learning
experience, and a few blemishes seem a reasonable price for running PC-level
GUIs on a phone.
Preface: as of May 2023, Mergeall's original tkinter GUI described here has been superseded on Android by the standalone app PC-Phone USB Sync. This new app uses Android's All Files Access permissions to regain access to both removable storage (e.g., USB drives) lost in Android 11 and general shared storage temporarily lost in Pydroid 3 version 6. Mergeall's tkinter GUI still runs on Android in Pydroid 3 today but is largely moot; please use the new app instead.
Mergeall—an incremental-backup and change-propagation system—can be used to sync on-phone content to and from removable media. This program has both a command-line mode usable in apps like Termux, as well as a tkinter GUI usable in Pydroid 3. Pydroid 3 has a Terminal interface too, but it's too limited to recommend for Mergeall's command-line mode. The following summarizes the expanded coverage in this document and augments Mergeall's base user guide. Note that Mergeall changes a destination folder by design; use it with care.
Mergeall's GUI looks like this when run on Android in Pydroid 3:
You can also view these screenshots in slideshow mode starting here.
Mergeall's GUI is usable in either landscape or portrait phone orientation, though portrait mode displays more run messages without scrolls, and landscape is less likely to truncate GUI content. Per usage notes ahead, rotating the screen after the GUI is running may not work on some devices.
Because Mergeall's GUI has no persistent popup windows and its exit verification can be skipped, it may render and work best using Pydroid 3's tkinter fullscreen and maximized viewing modes, the latter of which automatically resizes for fit on rotations. Select these modes by turning the first "Tkinter" switch off and the second on in Pydroid 3's Settings ⇨ System dialog before running the GUI, and press your phone's back button twice to exit the GUI. Mergeall's GUI can be run in non-fullscreen and non-maximized viewing modes too (see the captures above), but they hold little usage advantage.
To run Mergeall on your Android device, follow these steps:
And move them to the top level of your unzipped Mergeall source-code package, replacing their original versions. Download by clicking "save" in the "Raw text" line of these links' pages, and search for "# ANDROID" to see code changes made if desired. Note: some browsers may append a bogus ".txt" to the end of a saved ".pyw" file's name; delete the ".txt" manually by renaming.
launch-mergeall-GUI.pyw in the Pydroid 3
app's editor and pressing the editor's big yellow run
button.
Mergeall's GUI should appear and work largely the same as it does on
PCs.
Naturally, only this last step must be repeated on later runs.
Also keep the following in mind when using Mergeall on Android:
launch-mergeall-GUI.pyw source-code file.
Shortcuts look like
this or
this
and can be made by multiple Android file explorers including the app
here,
but be sure to set the default app or command to Pydroid 3.
Tip: uncheck "Parameters" when making shortcuts in Total Commander 3.0
(details).
On some devices, Pydroid 3 either kills the GUI silently or hangs altogether if the screen is rotated between portrait and landscape orientations while a tkinter GUI is running. Per details here, rotations are known to fail on multiple Samsung devices, but the latest of these rotate correctly if they avoid the Small screen-zoom display setting. If your rotates don't work, change your screen zoom to Medium or Large, apply system updates, or don't rotate.
In the same department as the preceding note: per here, changing phone orientation during a spawned activity (e.g., a Share or program-help browse) may cause the GUI to slide off screen or similarly hang, even on devices that handle rotations in general. Rotate twice to restore the GUI where supported.
Removable media used with Mergeall on Android should generally be formatted as FAT32 instead of exFAT, due to an existing Android exFAT timestamp bug which may skew file modification times both read and written (by 16 hours in US Pacific time) and hampers Mergeall file comparisons. To date, this bug has been observed on Samsung Android devices only, though it appears on multiple such devices, and its full scope is unknown. Note that file times on FAT32 drives may need to be adjusted on daylight-savings-time (DST) rollovers to make them compare correctly with times on non-FAT drives that use UTC-based time; for details and instructions, see this note.
Mergeall can be used with both Termux command lines and Pydroid 3 GUIs.
The full story on its storage constraints for Termux and Pydroid 3 is
here and
here. In brief,
because both Termux and Pydroid 3 can update only their own app-specific
folders on removable media, you must either choose which app will update
removable-media content and nest it appropriately (see the next note),
or locate your content anywhere in internal storage (e.g., /sdcard)
where it can be updated by both apps.
If you choose to use Mergeall in Pydroid 3 only, content that will only
be read can be located anywhere. Content that will be updated
can be located anywhere in internal storage (e.g., /sdcard),
or nested in Pydroid 3's app-specific folder created manually on removable drives
and named as follows (where the xs are your drive's Android ID):
/storage/xxxx-xxxx/Android/data/ru.iiec.pydroid3
Merging to removable media looks like this in the GUI.
cpall.py utility from a command-line interface;
or by running a sync in Mergeall's GUI to an empty folder.
See the Mergeall-on-Android how-to's extended coverage
here and
here.
helvetica,
but its other font limitations described here are still present.
Because some font types cause tkinter GUIs to crash silently in Pydroid 3,
Mergeall's configuration file mergeall_configs.py was changed
to disable text-area font customization by presetting it to None, which
applies the system default.
Experiment with font settings in this file as desired. In general, font families courier,
times, and helvetica work (and monaco is
courier and arial is helvetica), but most
others crash the GUI, and italic and bold styles are ignored for courier.
You can still use the GUI's
Browse buttons
to pick arbitrary folders as before (in addition to manual entry
and file-explorer copy/paste), but the new starting-folder settings can
make the dialog less frustrating, and the new prefills will likely suffice
in most common usage (and are the Pydroid 3 GUI equivalent of
Termux command-line $plug and $data shell
settings).
The logfile default folder was also changed to Admin-Mergeall
in /sdcard; its former Documents might not
exist unless you run MS Office apps.
Tip: if you opt to use the Browse file-chooser dialogs instead of the new prefill settings (or must use the dialogs for a run's unique requirements), spread/pinch zooms can make these dialogs much more usable, especially on smaller displays. See the general tkinter usage notes here for more.
If labels are still too wide for a smaller phone you use,
either interact with the GUI in landscape mode for more
space (and rotate to portrait to see more messages where
supported);
edit the code to shorten labels further (search for
"# ANDROID - shorter" in
launch-mergeall-GUI.pyw
to find labels' text);
or simply change the new LABELFONT setting in the
configurations file to
a smaller
