Simpler Command Line Tools for Everyone

The updated Mapillary command line tools make uploading and preprocessing your imagery easier—and not just for programmers.

With the increasing amount of images contributed all over the world, we’re striving to remove barriers to creating fresh map data. Today, we release an update to our command line tools to streamline importing imagery to Mapillary.

Command line tools help automate the upload flow and handle larger volumes of imagery, whether it’s captured with our mobile apps or other cameras. They’re particularly useful when you capture with multiple cameras and with high frequency. The tools also include pre-upload processing (such as removing duplicates and correcting compass angle data) so that you don’t need to edit imagery post-upload.

Contributing imagery to Mapillary

A lot of our contributors are no strangers to code, making it natural for them to use the Python scripts in the Mapillary toolset. Others don’t normally work with code so it might seem scary to use the command line. It shouldn’t be!

This update is all about making things easier and more efficient. The tools are now simpler and much better documented so that everyone should be able to get started. Just take a breath and dive in! You’ll get used to it in no time and can upload more with less effort.

We want to say a big thank you to our community! You have contributed a lot of ideas, bug reports, and code to these tools over time, helping us shape them into what we’re releasing today.

One tool to rule them all

The updated set of mapillary_tools has condensed the numerous Python scripts previously available into just one executable. You now only need to run mapillary_tools on your command line with either process or upload (or both, to do them together) and specify a minimum of required arguments: the path to the image folder and the username of the account you want to upload to.

At the same time, there are some advanced options available to handle less ordinary use cases such as sampling images out of a video file, geotagging the images, removing duplicate images (e.g. taken while you were stopping at a traffic light), etc. For detailed instructions, additional tools and arguments, but also general use tips, make sure to go through the readme.

Command line tools helped import the 800,000 images that the City of Amsterdam brought to Mapillary, making map data available in less than a week.

Authentication interface

When using the tools for the first time for a user account, you will be prompted to enter the Mapillary login credentials. A global configuration file for this user will be generated and used for future imports. Differently from the previous version, there is no need to provide any additional user variables like upload hashes.


Getting started is now simpler as there is an installation package that contains everything you need for the tools. Besides the executable tool, the package can also be imported in Python and used as a library, meaning that you can easily implement your own custom scripts if you want (the tools repository is open source).

Technical improvements

Those who have used our tools before will notice a few changes in the process. First, files are no longer moved around into new folders to signify their status. Instead, logs are kept in a hidden directory called .mapillary in the source folder of the import, containing all the processing results and the required and optional image metadata.

Reading latitude and longitude from external sources such as GPX files, rather than image EXIF, is simpler now and enables easier integration of new external sources. For example, this can also mean reading the location information straight from a geotagged video file which some cameras record.

Next in line for us is to move from Python 2 to Python 3 so stay tuned for more updates.

Let us know

We hope you find the updated tools easy to use. You’ll find them in the mapillary_tools repository together with extensive documentation. Try it out and let us know what you think; also, give it a try even if you haven’t been using much code before. We’d love to get your feedback to make it even easier to use the tools (and also if you need help—just email us).


Note. If you've been working with the previous tools, please use those to finish any partially uploaded sequences you may have in progress before you switch to the new version (because the logging procedure is incompatible).

Continue the conversation