25% OFF First Invoice

Code at Checkout: APEX25

Minecraft ImageOnMap Plugin

Last modified on Aug 16, 2023 in Plugins

mc head By Nathan Young


Customizing your structures with decorations on Minecraft servers can take many different forms. Whether you’re using default paintings or vegetation, there’s lots of possibilities. However, using plugins for Spigot or Paper provide you with even more to decorate your base. One of these is known as ImageOnMap, implementing new commands that convert online images to in-game maps for you to palace on item frames. This means you can have anything displayed on your Minecraft server. For example, custom artwork you created can be introduced to everyone in the world. Otherwise, pictures you liked online can be added instead. Regardless of what you decide to do, there’s endless opportunities to personalize your buildings. Setting this up to play with friends is easily done on our panel, but may confuser newcomers to the scene. Due to this, we’ve created this Apex Hosting guide to show you how to install and use ImageOnMap on your Minecraft server.

How to Download

  1. Navigate to the ImageOnMap plugin page on Spigot’s website.
  2. Continue to locate and press the Download Now button near the top right corner.
    ImageOnMap Minecraft
  3. Save this file somewhere easily accessible on your computer for later.


Minecraft servers using 1.14 to 1.16 versions require the 4.1 build of ImageOnMap. The 1.13 types need the 4.0-pre1 of this plugin, while anything else must have 3.1 to have full support. Accessing these specific versions is straightforward, as you’ll want to click Version History at the top of ImageOnMap’s Spigot page. Afterward, simply press the Download button to begin receiving the file. As for Minecraft 1.17 and above, the latest build of the plugin is required.


Server Installation

Before using this plugin, you’ll need to install Spigot, Paper, Purpur, or other similar types. This is required to have plugin compatibility, making it necessary to begin playing. Doing this requires you to select one of them with your desired version from the Game File area in the main panel. Afterward, restarting the server to generate its files is needed. Once you’re finished, follow along below to start enjoying the ImageOnMap plugin.

  1. Head towards your Apex server panel, then click FTP File Access near the top left.
    Minecraft FTP
  2. Type your Password in the text box and press the Login button to gain access.
    Minecraft FTP Login
  3. Locate and enter the plugins directory from the list, then at the top left click Upload.
  4. Proceed to drag and drop the ImageOnMap file in the respective area.
    ImageOnMap Installation
  5. Wait for this to reach 100%, then return to the main panel and Restart the server.


Getting Started

ImageOnMap Plugin

Upon joining the server, anyone can begin using the ImageOnMap plugin due to its design. By default, all players should be able to run its commands to generate pictures on maps. If you’re wanting to limit this access to only some users, then setting up permissions is required. We’ll discuss this later on in the tutorial, among other aspects to get you started with this plugin. Besides this, prepare by saving desired image links and keeping their sizes in mind. Afterward, executing a specific command will render the picture for you to display on a map. All of this is automatically done after running the action, meaning it’s completely user-friendly. There’s even a management system for you to easily navigate all images. Review the subsections below to begin learning more about ImageOnMap to get started.

Finding an Image

As previously mentioned, you’ll need to locate an image online and save its URL for later. This will be used for generating the map with it, but must meet a few requirements. For example, you cannot have invalid file types, such as .webp or other similar types. In other words, all images should be .png or .jpg for it to successfully work without problems. Additionally, if the link is too long there could be issues with it in-game. We strongly recommend using a web image service such as Imgur, especially if you’re wanting to upload your own material.

ApexHosting Animation


Generating Maps

ImageOnMap Guide

As for generating maps with your images, there’s two commands to do that. These include /tomap and /maptool new, with the latter being highly recommended for Minecraft versions above 1.17. Each one follows the same argument format, [URL] [resize], which renders the image automatically after running it. For instance, “/tomap example.com/test.png resize 1 1” generates the picture at a one-to-one scale to fit everything in the map.

These resizing values are preferred, but there’s more that’ll help you get larger images to display. For even larger images, using resize-stretched or resize-covered while generating one is suggested. These tend to be for better resolution, but require tons of item frames depending on your setup. It’s advised to only stick with the normal resize scaling options, rather than trying out other ones.

Using Maps

Players wanting a larger image can use “resize 4 4” or other scaling options, generating a splatter map that requires multiple item frames to be displayed. Whether you want a 3×3 or 10×10 setup, you have many possibilities to try out. Keep in mind that you’ll need a lot of frames if you make it too large, which can lower performance on the server in some cases.

ImageOnMap Tutorial

Besides this, once you’re ready to display the image, simply right-click the bottom left item frame to instantly make the picture appear. Removing it requires you to shift + left-click anywhere on it, making it easier to delete.

Map Management


If you and others have too many maps, it can be difficult to find the ones you want. Fortunately, you can use the /maps command to view all of them without issues. Simply select the one you want, but right-clicking reveals more options. This allows you to rename, delete, or take specific parts of a large image. Remember, all players have access to this ability and other commands. This means anyone can simply grab, delete, and do other actions with your maps.



In some cases, server owners may want to limit what players can do with ImageOnMap. This is amplified if there’s too many maps in the world, as this can decrease performance in specific regions. In these situations, reviewing our Minecraft Server Optimization Guide is suggested. Otherwise, installing LuckPerms and manually assigning permission nodes to users or groups is another option. Removing default access to ImageOnMap requires you to add and disable them. As for the different ones to use, review the table below to learn more.

/tomapImageonmap.newAccess to the main command for generating images on maps.
/mapsimageonmap.listGrants the player the ability to open the Maps menu.
N/Aimageonmap.getProvides the user with the power to obtain maps from the menu.
N/Aimageonmap.renameProvides users the action to rename maps from the menu.
N/Aimageonmap.deleteProvides a player with the ability to delete maps from the menu.
/maptool newimageonmap.newAccess to the second command for generating maps.
N/Aimageonmap.*Grants all permissions and commands to the player, excluding imageonmap.administrative.



If you’re unhappy with how players are using maps, then consider limiting their uses and sizes. This is done by tweaking ImageOnMap’s configuration file from the FTP panel. Make sure to follow the exact format as it appears in the editor. Once you’re ready, review the instructions below to start this process.

  1. Navigate to the FTP File Access area and use your login credentials accordingly.
  2. Proceed to the following directory pathway: …/plugins/ImageOnMap
    ImageOnMap Config Folder
  3. Find and click the Edit button to the right of config.yml, revealing its file editor.
    ImageOnMap Config File
  4. Continue to make your desired changes, then press the Save button at the top.
    ImageOnMap Settings
  5. Restart the server from the main panel to begin loading these edits.


Common Issues

ImageOnMap Isn’t Working

If you’ve noticed that the plugin itself isn’t working properly or loading on the server, then there could be a few reasons for that. The first is failing to select Spigot, Paper, Purpur, or other similar types to support ImageOnMap. Remember, this is important since plugins only work on supported server types. Additionally, double check the game version isn’t too outdated compared to what ImageOnMap offers. However, the situation may persist if you’ve failed to successfully upload the file into the plugins directory from the FTP panel. It’s best to delete what you’ve previously transferred, then doing it again to ensure the process reaches 100%. Afterward, make sure to give the server a restart to begin loading everything properly.

Invalid Command Argument

While trying to generate an image on a map, ensure the URL is valid. This means it isn’t too long with unnecessary strings attached, meaning it should only end with the file type (.png, .jpg, etc.). However, the resizing of your image can also trigger this error to appear in-chat. For example, incorrectly typing “resize-stretched” can result in this situation. Otherwise, it could be due from an outdated version of the plugin on a newer Minecraft server. ImageOnMap works best on 1.17, while 1.19 has a harder time generating large images.

Unable to Retrieve NBT Data

If you’re noticing this error in the Console after trying to create large images with your maps, try installing another build of the plugin. Remember, there’s specific ones for certain game versions. Any server using 1.14 to 1.16 needs to have the 4.1 build, while 1.13 requires 4.0-pre1. If you’re on something else that’s older, then only use 3.1 for the ImageOnMap plugin. Otherwise, using the latest version should be sufficient for everything to work properly.

Useful Links

ImageOnMap on Spigot
How to Add Plugins to a Minecraft Server
Install and Using LuckPerms on Minecraft
Becoming a Minecraft Server Operator

Start Your Minecraft Server

Get started with your own minecraft server in 5 min and start trying out these great features.