Download your own Mapillary images in full resolution for a local backup. Supports incremental downloads, date and camera filters, EXIF restoration, a dry run with size and time estimates, and Docker.
Run it again at any time: already downloaded images are skipped automatically. This makes it suitable for regular backups, for example with a weekly cron job. The images are sorted by day and sequence.
Please note: images are downloaded at their original resolution, but they are not the original camera files: Mapillary applies privacy blurring (faces, license plates) and re-encodes them. The script restores the available metadata (GPS position, capture time, compass direction and camera) as EXIF tags. Keep the files from your camera as the real backup!
(or use the Docker image, see Docker; for Windows see Windows)
| System | Install |
|---|---|
| Debian 12 or newer | sudo apt-get install python3-requests python3-piexif |
| macOS | brew install python3 && python3 -m pip install requests piexif |
| FreeBSD | pkg install py311-requests p5-Image-ExifTool |
| others | python3 -m pip install requests piexif |
piexif is used if both piexif and ExifTool are installed, it is faster. If neither is installed, the images are downloaded without restored EXIF metadata and a warning is printed.
The API v4 does not support a login with email and password anymore. Instead you need an access token:
MLY|Pass the token with --token or set the environment variable MAPILLARY_TOKEN.
Keep your access token private: do not commit it to Git, put it into scripts you share with others, or publish it in logs.
Download and unpack the latest version:
curl -O -sf https://download.bbbike.org/src/mapillary-takeout-v4/mapillary-takeout-v4-latest.tgz
tar xfv mapillary-takeout-v4-latest.tgz
cd mapillary-takeout-v4-*/
export MAPILLARY_TOKEN='MLY|...'
./mapillary-takeout-v4.py your-mapillary-username /path/to/backup
You can run the script again at any time. Already downloaded images are skipped automatically.
The script is executable after unpacking. If your shell says
Permission denied, run chmod +x mapillary-takeout-v4.py, or start it with
python3 mapillary-takeout-v4.py.
First, check what would be downloaded, with an estimate of size and time:
./mapillary-takeout-v4.py --dry-run your-mapillary-username /path/to/backup
mapillary-takeout-v4.py x.yy - download your images from Mapillary (API v4)
https://download.bbbike.org/src/mapillary-takeout-v4/
Settings:
...
takeout started at: Thu 29 Oct 2026 21:14:35 CET
2026-10-25 14:03Z 8f3kQ2pLx9... 600 images 1.7 GB Apple iPhone SE (2nd generation)
2026-10-27 09:12Z 2m9xL7vTq1... 275 images (of 300) 770.0 MB Apple iPhone SE (2nd generation)
875 images in 2 sequences to download, 25 already downloaded (all in subfolders)
Estimated download size: 2.5 GB (2.8 MB/image, based on 125 downloaded images)
Size estimate: 875 images by average size of the same camera model (in the same year, if possible)
Estimated download time: 2 Gbit/s: 11s, 1 Gbit/s: 22s, 500 Mbit/s: 44s, 250 Mbit/s: 1m 27s, 100 Mbit/s: 3m 38s, 50 Mbit/s: 7m 15s, 16 Mbit/s: 23m
Free disk space: 1.2 TB
HTTP requests: 1 search, 2 image lists (0 failed)
takeout ended at: Thu 29 Oct 2026 21:14:38 CET
With --debug 0 only the summary is shown:
./mapillary-takeout-v4.py --dry-run --debug 0 your-mapillary-username /path/to/backup
875 images in 2 sequences to download, 25 already downloaded (all in subfolders)
Estimated download size: 2.5 GB (2.8 MB/image, based on 125 downloaded images)
Estimated download time: 2 Gbit/s: 11s, 1 Gbit/s: 22s, 500 Mbit/s: 44s, 250 Mbit/s: 1m 27s, 100 Mbit/s: 3m 38s, 50 Mbit/s: 7m 15s, 16 Mbit/s: 23m
How the size is estimated and what the HTTP requests line means: see
DETAILS.md.
Download only images captured in October 2026, including the metadata as a
.json file next to each image:
./mapillary-takeout-v4.py --metadata --start-date 2026-10-01 --end-date 2026-10-31 your-mapillary-username '/path/to/MY BACKUP'
Both the start and the end date are included. The dates are in UTC.
Download only the images of the last 14 days: today and the 14 days before,
15 calendar days in total. This is useful for a weekly cron job: it also
catches uploads which were processed late by Mapillary, and a missed run.
With --debug 0 the script is quiet like
other Unix tools: no progress, only errors and warnings, which go to stderr.
So cron sends an email only if something went wrong:
./mapillary-takeout-v4.py --debug 0 --last-days 14 your-mapillary-username /path/to/backup
Limit a run, e.g. a cron job at night: --max-time 8h stops after 8 hours
(also during the search), --max-size 50G after 50 GB downloaded. Downloads
already running finish cleanly, the script exits with status 1 and the next
run continues where this one stopped:
./mapillary-takeout-v4.py --max-time 8h --max-size 50G your-mapillary-username /path/to/backup
Store the images exactly as served by Mapillary, without writing EXIF:
./mapillary-takeout-v4.py --no-exif your-mapillary-username /path/to/backup
Show which cameras you used and how many images each has:
./mapillary-takeout-v4.py --list-cameras your-mapillary-username
images make model
5,210 Apple iPhone 13 Pro
1,830 GoPro HERO9 Black
Download only the iPhone pictures:
./mapillary-takeout-v4.py --model iphone your-mapillary-username /path/to/backup
--make is the camera manufacturer (also --manufacturer), --model the
camera model, as shown by --list-cameras and stored in the EXIF tags Make
and Model. Download only the GoPro pictures:
./mapillary-takeout-v4.py --make gopro your-mapillary-username /path/to/backup
--make and --model are case-insensitive substrings, so --model iphone
matches "iPhone 13 Pro" as well as "iPhone 15". Images without camera
information are listed as unknown.
Each sequence gets its own folder, below a folder for the day:
<output_folder>/<YYYY-MM-DD>/<captured_at>/<captured_at>_<sequence_id>_NNNN.jpg
<output_folder>/<YYYY-MM-DD>/<captured_at>/<captured_at>_<sequence_id>_NNNN.json (with --metadata)
NNNN is the position of the image in the sequence, <captured_at> is the
start time of the sequence. With --no-subfolder all images of a day are
stored in the day folder:
<output_folder>/<YYYY-MM-DD>/<captured_at>_<sequence_id>_NNNN.jpg
Both layouts are recognized, see DETAILS.md for more.
The Dockerfile builds an image based on Debian 13 (trixie) slim with all
packages the script needs: python3, requests, piexif, exiftool and tzdata.
Build the image:
docker build -t mapillary-takeout .
Download into the folder backup in the current directory:
mkdir -p backup
export MAPILLARY_TOKEN='MLY|...'
docker run --rm -e MAPILLARY_TOKEN --user "$(id -u):$(id -g)" \
-v "$PWD/backup:/backup" mapillary-takeout your-mapillary-username /backup
All options work as usual, e.g. the last 14 days in local time:
docker run --rm -e MAPILLARY_TOKEN -e TZ=Europe/Berlin --user "$(id -u):$(id -g)" \
-v "$PWD/backup:/backup" mapillary-takeout --last-days 14 your-mapillary-username /backup
-e MAPILLARY_TOKEN passes the token from your shell into the container,
it is not stored in the image. Use the variable name without $:
-e MAPILLARY_TOKEN. Writing -e "$MAPILLARY_TOKEN" passes the token as an
environment variable name instead, so the container doesn't get the token.
The variable must be exported (export MAPILLARY_TOKEN=...); if it is not,
use -e MAPILLARY_TOKEN="$MAPILLARY_TOKEN".--user "$(id -u):$(id -g)" lets the files in backup belong to you
instead of the container user (uid 1000).The script is not tested on Windows. The easiest way is to run it like on Linux, in WSL (Debian or Ubuntu) or with Docker Desktop.
It should also work with Python for Windows:
python -m pip install requests piexif
Set the token in cmd (the quotes are needed because of the |):
set "MAPILLARY_TOKEN=MLY|..."
python mapillary-takeout-v4.py your-mapillary-username D:\mapillary-backup
or in PowerShell:
$env:MAPILLARY_TOKEN = 'MLY|...'
python mapillary-takeout-v4.py your-mapillary-username D:\mapillary-backup
Differences from Linux and macOS:
* Windows does not allow : in file names, the times in the file and folder
names are written as 10_00_00 instead of 10:00:00. A backup made on
Windows is not recognized on Linux or macOS and the other way round, all
images would be downloaded again. WSL and Docker use the Linux names.
* There is no lock file, two runs at the same time for the same folder are
not prevented.
| Exit status | Meaning |
|---|---|
| 0 | all images downloaded, or nothing to do |
| 1 | errors during the download, some images are missing, or --max-size/--max-time reached (run the script again later) |
| 2 | invalid options or usage, e.g. a wrong date or a missing access token |
| 3 | authentication or API error, nothing could be downloaded |
| 75 | another run is already downloading into the output folder (EX_TEMPFAIL, like lockf -t 0) |
| 130 | interrupted with Ctrl-C (run the script again to continue) |
A date range without any images (e.g. --last-days 1 on a day without
uploads) is not an error.
| Problem | What to do |
|---|---|
Authentication failed (exit 3) |
Check the token, see Access token. In Docker see the note on -e MAPILLARY_TOKEN in Docker. |
| The API refuses to search without a bounding box | Add the area where you took your pictures, e.g. Berlin: --bbox 13.0,52.3,13.8,52.7 |
neither the Python module piexif nor exiftool was found |
Install piexif or exiftool, see Requirements, or use --no-exif. |
Not enough disk space |
Free some space, download a shorter date range, or see --disk-reserve in DETAILS.md. |
Another mapillary-takeout is already running (exit 75) |
A run for the same folder is still going, see the lock file in DETAILS.md. |
not available at Mapillary in original size |
Mapillary has no original for these images, --fallback-2048 downloads the 2048 px version. |
| Some images missing (exit 1) | Run the script again later, it downloads only what is missing. |
Stopped: --max-time 8h reached (exit 1) |
The run stopped at the limit you set, see Common options. The next run continues. |
DETAILS.md has the size estimate, the full folder layout, how the
script works (search, retries, disk space check, EXIF, memory), the full list of
options and how to run the tests. ./mapillary-takeout-v4.py --help shows all options.
Check which version you have:
./mapillary-takeout-v4.py --version
At startup the script checks in the background whether a newer version is available, and shows a note at the end of the run:
A newer version 2.80 is available (you have 2.71):
https://download.bbbike.org/src/mapillary-takeout-v4/
--version checks too: it prints the version number alone on stdout (for
scripts), and the note about a newer version on stderr.
The check asks download.bbbike.org for the latest version number, so the
server sees your IP address. It never delays or stops a backup, and it shows
nothing with --debug 0 (cron jobs). Turn it off with --no-version-check or
the environment variable MAPILLARY_TAKEOUT_NO_VERSION_CHECK=1 (e.g. in Docker
with -e MAPILLARY_TAKEOUT_NO_VERSION_CHECK=1).
Version 2.x uses the Mapillary API v4 (graph.mapillary.com). Version 1.x was written for the old API v3 on the Amazon AWS infrastructure, which Mapillary shut down in June 2021. See the history.
Homepage: https://download.bbbike.org/src/mapillary-takeout-v4/
General questions about Mapillary (your account, uploads, the Mapillary apps or the API itself) are better discussed in the Mapillary forum: https://forum.mapillary.com/
Questions, bug reports and ideas: Wolfram Schneider wosch@FreeBSD.org
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details