Many people use JOSM for mapping as the power and versatility of this program is unlike anything else available and is irreplaceable for many tasks.
While mobile versions of mapping tools exist, they often do not include the advanced plugins, validation rules and everything else that makes JOSM so useful to us. Many mobile applications focus more on surveying and entering data rather than the mapping itself. While there are powerful exceptions to this rule like Vespucci they still aren’t on quite the same level.
Here I’ll show how I used Termux and Proot-Distro environment tb bring a full, desktop version of JOSM to android.
In this guide I ran everything on my Samsung Tab S7+, it has a very large screen large enough to run JOSM on without feeling cramped, for any smaller devices such as mobiles I recommend finding some way to display it on a monitor as otherwise the screen will be way too small to do anything useful.
Naturally a mouse and keyboard are strongly recommended as trying to navigate the full JOSM interface on just a touchscreen would be crazy challenge!
While this isn’t a difficult task to achieve you’ll still need a certain level of skill in navigating the command line and be comfortable to experiment to find your perfect setup.
I haven’t tested every single function available but after doing hours of mapping I haven’t run into a single issue yet, other than the occasional crash if I try to have too many applications open at the same time.
I’m sure this isn’t the only method that’ll work, this is the one that I’ve found to be not too painful and pretty consistent with how it runs.
JOSM running on my Pixel 9 Pro XL. It works but might need a larger screen…
CAUTION
Important: Do not use the version of Termux on the Google Play Store. It is deprecated and will not work for this setup. Use the builds from GitHub or F-Droid as linked below.
Method
1: Install Termux and Termux:X11
Termux is an Android terminal emulator and Linux environment app that works directly with no rooting or setup required. This is the main system that everything runs on top of.
Download the version from Github or F-Droid. NOT the version from google play as it is out of date!
Termux install: Termux | The main termux site and help pages.
Termux-X11 is the graphical environment (X server) which will display JOSM while working.
Termux-X11 install: GitHub - termux/termux-x11: Termux X-server add-on.
Termux-X11 wiki: Making sure you're not a bot!
2: Setup the linux environment in Termux
The system runs on a Linux distribution using PRoot to simulate a chroot environment. Basically what this does is allows us to run a full Linux user space, install packages and manage containerised environments all from our android system!
This enables us to run a system that is completely isolated from everything else device (if wanted), it also allows us to run programs that were developed for different CPU architectures e.g. x86_64 on ARM64.
Proot-distro supports many different linux distributions however in this we will use Ubuntu, no proper reason as to why that’s just my preference however I’m sure others such as Debian or Mint will work just as well.
# Update and install core tools on termux
pkg update && pkg upgrade
pkg install x11-repo termux-x11-nightly proot-distro
# Install Ubuntu (or Debian) container
proot-distro install ubuntu
proot-distro login ubuntu
3: Install JOSM and graphics support
We need various other packages to support running the x-server display and also the java application itself.
openjdk-17-jre: A free open source java runtime environment based on the java 17 platform, this provides the essential libraries and java virtual machine (JVM) required to run java applications
openbox: This is a configurable window manager for the X-Window system. This is used to help display the JOSM application, I had issues with scaling and also maximizing the window once opened and openbox sorted it right out
wget: World Wide Web get - tool to retrieve content from the web via command line
apt update && apt upgrade
apt install openjdk-17-jre openbox wget
# Create a persistant JOSM folder and download the JOSM application
mkdir -p ~/josm && cd ~/josm
wget https://josm.openstreetmap.de/josm-tested.jar
4: Running the application
It’s easiest to run the bash program I’ve made which does all the heavy lifting for you but it’s important to understand what’s happening in the background.
It’s basically 3 distinct parts:
4.1. Starting the Linux environment
Open both Termux and Termux-X11, then within the Termux environment enter;
proot-distro login ubuntu --shared-tmp
--shared-tmp is important here as it shares the /tmp folder between termux and Ubuntu, this is what allows Ubuntu to communicate with the Termux-X11 display app.
4.2. Starting and setting up the display
Start the termux-x11 display server on display 1, the & runs it in the background so we can continue using the terminal. Please read the section below ‘Termux-X11 screen enhancements’ to make it look nicer.
If you get any errors make sure that the Termux-X11 app is open first
termux-x11 :1 &
Tells Ubuntu which display to send the window to. Note that there are NO spaces between DISPLAY= and :1
export DISPLAY=:1
This launches the window manager and allows us to move, resize and minimize JOSM. Otherwise JOSM would just be a static box in the middle of the screen.
openbox &
You may get a warning about ‘Unable to find valid manu file’, it’s a harmless warning and doesn’t matter for this, but if you want to fix this you can run;
apt update
apt install menu -y
update-menus
4.3. Launching JOSM Java application
This looks long and complicated but boils down to simply java -jar ~/josm/java-tested.jar, everything else added in is just for ease of life. I’ll explain it below.
java -Xmx4G -Dsun.java2d.uiScale=2 \
-Djosm.home=/root/josm/.josm \
--add-exports=java.base/sun.security.action=ALL-UNNAMED \
--add-exports=java.desktop/com.sun.imageio.plugins.jpeg=ALL-UNNAMED \
--add-exports=java.desktop/com.sun.imageio.spi=ALL-UNNAMED \
-jar ~/josm/josm-tested.jar
-Xmx4G: Java can be very memory heavy, especially if mapping a whole village with satellite imagery etc, this allocates 4GB of memory to the Java application so that it does not take anymore. It can also be written as -Xmx4096M if you so wish. 4GB is just what works on my tablet with 6GB of memory, change this as needed for your device.
-Dsun.java2d.uiScale=2: This sets the scale of the application so that menus are easier to navigate, by default it is 1 but I found that to be too small on my tablet.
-Djosm.home=~/josm/.josm \: Sets the home folder for JOSM, allows persistent storage for plugins, themes, settings etc.
The ones below came up as warnings the first time I ran JOSM, adding these in made it happy. The explanations came from AI so take with a pinch of salt.
--add-exports=java.base/sun.security.action=ALL-UNNAMED \: Allows JOSM to access internal security settings. It needs this to properly handle OpenStreetMap login credentials and secure connections.
--add-exports=java.desktop/com.sun.imageio.plugins.jpeg=ALL-UNNAMED \
--add-exports=java.desktop/com.sun.imageio.spi=ALL-UNNAMED \: These two lines are for satellite imagery and unlocks high-performance decoding of JPEGS and handling of image data.
To exit at any point just press the X in the top right of the JOSM window or press CTRL-C when on Termux CLI. Make sure to exit out of everything properly.
5. BASH start program
This is a custom launch script that I wrote to handle everything we just talked about, it lives in my root termux folder and is run with ./josm.sh. It comes with a default window scale modifier but can be easily changed by providing an argument after the command e.g. ./josm.sh 1.0 for 1x scale.
#!/bin/bash
# waits for scale modifier,
# default is 2.0 as that worked best on my tab S7+
SCALE=${1:-"2.0"}
# 1. Start ubuntu proot-distro
# Everything after the -- is executed inside ubuntu
proot-distro login ubuntu --shared-tmp -- bash -c "
sleep 2 #waits for 2s, helps proot-distro 'boot' up before issuing commands
# 2. Start the X11 server within the distro
pkill -9 termux-x11 #initial kill just to avoid issues
termux-x11 :1 &
sleep 3 #waits for 3s for display to activate
#3. Initilise the display
export DISPLAY=:1
openbox & #used for windowing and scale
#Capture manual exit commands
trap 'echo \"Stopping JOSM loop...\"; exit' SIGINT
# 4. Wrap the jar file in a bash restart loop,
# this reopens it if it closes for any reason like changing themes
while true; do
echo 'Starting JOSM at scale=$SCALE'
# 5. Open josm jar file
# Needs these options to set scale, maintain user data and to stop warnings when opening
java -Xmx4G -Dsun.java2d.uiScale="$SCALE" \
-Djosm.home=/root/josm/.josm \
-Djosm.restart=true \
--add-exports=java.base/sun.security.action=ALL-UNNAMED \
--add-exports=java.desktop/com.sun.imageio.plugins.jpeg=ALL-UNNAMED \
--add-exports=java.desktop/com.sun.imageio.spi=ALL-UNNAMED \
-jar ~/josm/josm-tested.jar
# Visual comfirmation of JOSM restarting
echo 'JOSM closed. Restarting in 2 seconds (Press Ctrl+C in Termux to stop loop)...'
sleep 2
done
"
You can do this too by creating your own executable script, copying in the above code and then granting it the appropriate permissions to run.
touch josm.sh
nano josm.sh #copy in text here, CTRL-O then CTRL-X to save and exit
chmod +x josm.sh
6. Logging in
To do anything useful i.e. uploading any changes we make to the map we need to be logged in. This is where things get a bit more finicky but still not too hard. JOSM by default uses OAuth 2 authentication, when pressing that it should open the web browser to take you to the appropriate login page, but because we are running a simulated Linux environment it can’t do that.
I’ve played around with opennbox and installing a web browser but it still didn’t want to play nice. If anyone is able to find a better/easier method please let me know and I can update this section.
Follow the following steps to login;
1. Open JOSM preferences and navigate to OSM-Server
2. Press the Authorise now (fully automatic) button
It won’t appear to do anything and that’s fine because it all happens in the background.
3. Go back to Termux CLI to find link
ALT-Tab to do it quickly.
Might have to scroll up a bit but you should see a line showing
GET https://www.openstreetmap.org/.well-known/oauth-authorization-server -> HTTP/1.1 200
The line below should start with Opening URL: https://www.openstreetmap.org/oauth2/authorize?response_type=code&client_id… It’ll be a relatively long link as it contains a load of client identifying arguments. This is mine (personal details obscured for security).
Copy the whole link given on that line and paste into your normal web browser, this’ll take you to a OSM authorization page, click the authorize button and then go back to the Termux-X11 display, it should be logged in now.
If you’re not sure press the Test Access Token button for confirmation it is fully logged into your account.
7. Termux-X11 screen enhancements
Termux-X11 by default shrinks the screen under the camera bump, most devices nowadays can display over or around it. It also has an annoying keyboard row which is useful if you’re using a mobile device but takes up precious screen space and is unnecessary if you’ve got a Bluetooth keyboard.
Preferences > Output > Fullscreen (toggle on)
Preferences > Output > Hide display cutout (toggle on)
Preferences > Keyboard > Show additional keys (toggle off)
Useful links
Linux CLI cheat sheet: Linux Commands Cheat Sheet - GeeksforGeeks
Termux wiki: Making sure you're not a bot!
JOSM wiki: https://wiki.openstreetmap.org/wiki/JOSM/
JOSM installation wiki: JOSM/Installation - OpenStreetMap Wiki
Hardware tested
Samsung Tab S7+, Android 13
Pixel 9 Pro XL, Android 16
JOSM Version 19481
Java 17.0.18
Uninstalling
As Termux is a containerised environment everything is contained within it’s own app files. If you want to uninstall/reset everything just do so by removing Termux as you would like any other app on your device.
Final remarks
As I said at the start this isn’t the only option, this is just the one that I’ve been using and have found to not be too painful to setup - if anyone else finds anything better or improves any of the steps let me know!