Recently I got around to making steps toward a better mobile-PC workflow. Until now, I’ve pretty much exclusively been using the community-developed orgzly-revived app on Android. My intention was to use orgzly-revived for simple todo management and another app for more note-taking purposes—but I could never find another app I was happy with on Android. But I happened to remember reading good things about the native Emacs app on Android a few months ago. So I tried it out… and was immediately sold!

The good and bad: what to expect on Android

First, let’s make sure our expectations are tempered: Emacs on Android won’t be as pleasant as the full desktop experience. ^{Of course. A phone’s screen is tiny, and unless you have a physical keyboard connected, you’ll have to manage with a virtual one (see Use a Special virtual keyboard). On top of that:}

Tooling

To have non-Emacs programs available, you have to install Emacs in a particular way with Termux to expose Termux’s binaries to Emacs. (See the recommended way to install Emacs.) The initial set up is longer, but it’s worth it.

File paths

Android “sandboxes” each app. You can think of each app having their own “section” of the file system that they can read or write to (unless they are given explicit access to that outside directory; see info "(emacs) Android Document Providers"). As such, one finds themselves fiddling with the obnoxiously long Android file paths if they want to, for instance, access their notes directory that is outside the Emacs app sandbox. ^{This is a minor inconvenience though.}

Writing to the file system

Relatively speaking, writing to the file system can be long sometimes. Not too long, but long nonetheless, As far as I’ve experienced, this has only been the case when saving files that are outside the Emacs sandbox.

So, really, the situation is pretty good!

And finally: YMMV on other Android devices. My current phone is the OnePlus 7 Pro running Android version 12.

Installation

Option 1

The first option is as easy as it can get, but you won’t have a way to access other CLI tools:

1. Download the F-droid app store. For the layperson who doesn’t know what it is: it’s basically an alternative to the Play Store. Some apps that can’t be on the Play Store (fact check, maybe link tk) are there.
2. Download the Emacs app.
3. Open Emacs! The version of Emacs as I write this that is available is Emacs 30.1.

Using Emacs this way is totally possible if all you need is elisp. But if you need other tools, like git, I recommend the second way to install Emacs.

Option 2 (recommended)

This option makes other CLI tools accessible to the Emacs Android application container. It is a little bit more of a hassle.

The method is outlined in this SourceForge repository. In essence, inside the termux/ directory of this SourceForge repository are modified Emacs .apk files. These .apk files allow the Emacs app container to access the Termux (explain what Termux is tk) app container, meaning the CLI tools installed with Termux will become accessible to Emacs. But the installation is specific; read the instructions detailed inside that repository. I will outline them briefly below, but be careful if you are reading this in the future, for the instructions could have changed relevantly.

In short,

1. Delete any existing Emacs or Termux apps.
2. Ensure you have enabled the setting that allows you to install third-party apps (i.e., non-Play Store apps) on your phone.
3. Install Termux. Don’t open Termux yet.
4. Select the .apk file appropriate to your phone. There are various .apk files for different versions of Emacs and devices.
5. Install Emacs through this .apk. (If your phone refuses to install the .apk, you might have selected the wrong type of .apk file for your device. So try different .apk files for the same Emacs version.)
6. In Termux, run pkg update && pkg upgrade. Say “yes” to each of the prompts.
7. Open Emacs.
8. Create a ~/.emacs.d/early-init.el and place the following inside of it:

   1 2 3

   (setenv "PATH" (format "%s:%s" "/data/data/com.termux/files/usr/bin" (getenv "PATH"))) (push "/data/data/com.termux/files/usr/bin" exec-path)

9. And you’re done! Programs installed through Termux will be made accessible to Emacs.

Configuring an Android-specific Emacs

Necessary reading: the manual

Chances are that you don’t know that the Emacs manual has its own section for the Android system: (info “(emacs) Android”). Before anything, I highly recommend you peruse this section, returning to and reading more deeply specific parts as you see fit. In particular, I found the following Info nodes essential:

• (info “(emacs) Android File System”) (This one is particularly important if you wan to understand what the ~/ path means for Emacs.)
• (info “(emacs) Android Document Providers”)
• (info “(emacs) Android Fonts”)
• (info “(emacs) Android Windowing”)

A lot of the information here is found directly inside these Info pages.

Additionally, I also think reading about Emacs' facilities for touchscreens and virtual keyboards (bet you didn’t know this was in the manual either!) is essential: (info “(emacs) Other Input”).

Moments like these are truly a testament to Emacs' dedication to an accessible editor.

How to configure your init.el on a mobile device?

Later I’ll explain how you make typing code on a touchscreen device easier by installing a handy virtual keyboard. But I highly recommend that until you’ve settled on a configuration you’re willing to type out that you heavily utilize the customize interface. This means accessing the Customize interfaces via the tool-bar ^{buttons then using your touchscreen to tap the buttons available in customize-mode buffers. (Then, if you prefer, after setting many options with Customize, you can refactor the options Customize put in your init.el into e.g. use-package forms.)}

If you haven’t used Customize much before, you can check out the available Customize commands via C-h a (apropos-command), search for “customize.” The most useful commands are:

• customize-group,
• customize-option,
• customize-face,

First step: A Better UI for touchscreens

The very first thing I did when I opened Emacs was enable these minor modes:

• modifier-bar-mode
• tool-bar-mode

and set tool-bar-position to ‘bottom, placing it closer to where my fingers and the virtual keyboard are.

Desktop users might have disabled these years ago in favor of keyboard-centric workflow, but they are awesome for touchscreens in my opinion.

Android-specific Commands and Options

There are a few built-in Android commands and options you should be aware of. (Pro tip: one can M-x Info-index or press i in the Emacs Info manual, itself accessible via C-h r, or M-x info-emacs-manual, then search for the string “android” to find all the specific mentions off “Android.”)

• Commands:
  • android-request-directory-access to request access to file paths of other apps
  • and its inverse, android-relinquish-directory-access.
• Options:
  • android-pass-multimedia-buttons-to-system,
  • android-intercept-control-space,
  • touch-screen-display-keyboard,
  • (and more not useful to me).

Also, don’t forget to let Emacs display over other apps. This is a device setting, not an Emacs one.

Use a Special virtual keyboard

Unless you have a physical keyboard connected to your mobile device, typing will be a pain. For that, we install a virtual keyword that gives us easier access to modifier keys, function keys, arrow keys, and symbols. As far as I know, there are currently two main options:

Having briefly tried both, I personally prefer the latter. Though the former works just fine if you like it.

Fonts

You might want a set of fonts not already installed on your Android system. If that’s the case, you should read the (info “(emacs) Android Fonts”) manual page.

That page explains that if you want to install fonts for your user (in the Emacs app container), you should place them in ~/fonts/. ^{Getting those fonts was somewhat cumbersome for me: I had to manually download them, unzip them with Termux, place them inside a directory Emacs had access to (see Android-specific Commands and Options), then copy them to ~/fonts/.}

Note: in my experience, fonts are not recursively checked inside this directory. That is, you should place your e.g. .ttf files inside that folder, not any subdirectories.

Tip: You can remap the volume buttons

Volume buttons are un-mapped by default (see android-pass-multimedia-buttons-to-system). That’s find with me, but if you feel inclined, you can rebind them to something else after setting android-pass-multimedia-buttons-to-system appropriately. Some possibilities would be for navigation between headings, tk list more.

Conclusion

In conclusion,

• Make heavy use of the Customize interface. (At least initially—after you’re comfy in Emacs, you can refactor it into a form more familiar to a desktop init.el.)
• Enable minor modes and options specific to touchscreen-driven usage.
• Install a virtual keyboard to get access to modifiers, function keys, and more.

Right now I’ve achieved a set up I’m happy with. I migrated the portions of my configuration relevant to org, org-capture, and org-node, but in the future if I need more from Emacs-on-mobile, I’ll look to expand my config as necessary. (This includes version-controlling my init.el.)

And finally: YMMV on other Android devices. My current phone is the OnePlus 7 Pro running Android version 12.

Bonus: My wish list

Touchscreen gestures

There is the built-in strokes.el, but strokes.el, as far as I can tell, does not work for touchscreens. Additionally, significant changes would be required to its code base to make it compatible for touchscreens. So, for now, we have to settle with virtual keyboards…

Automatic keyboard/IME switching

Ideally, I’d have my special virtual keyboard be automatically selected using Emacs and deselected when not using Emacs. Right now, I have to manually switch to it. As far as I know, there is no easy way to accomplish this.

Larger tool bar and menu bar

The tool bar and menu bar are useful, but they’re also small. I wish they were larger and easier to tap.