How to Install BlueMap: 3D Web Map for Your Minecraft Server

What is BlueMap?

BlueMap is a free, open-source add-on that renders your Minecraft Java world as a 3D map and serves it as a website from your server. Players open the map in any modern browser, zoom out to see the whole world from above, or move down to a free-flying 3D view and look at buildings at block level.

Three things make it popular:

• 3D, not a flat image. The map is rendered in 3D (in the browser with WebGL), with terrain, buildings, water and lighting. Far away from the camera it switches to a simpler low-resolution version, so even large worlds stay smooth.
• Built-in web server. BlueMap comes with its own small web server. You don't need a separate website, hosting or nginx – the server that runs the game also serves the map.
• Live players. In the plugin and mod versions, players online on the server are shown on the map as markers.

It only works for Minecraft Java Edition – Bedrock servers can't run BlueMap.

Which BlueMap version do I need: plugin or mod?

Pick the version that matches your server engine: the plugin for Paper, Purpur or Spigot, the mod for Fabric, Forge or NeoForge. Both versions render the same map; they only load differently.

A pure Vanilla server doesn't load plugins or mods, so it can't run BlueMap as an add-on. Switch the server to Paper or Purpur first (your world can stay) – the differences between engines are explained in Minecraft server software. For modded servers, use the BlueMap build for exactly your loader and Minecraft version, and check the mod page for required libraries (the Fabric version needs Fabric API).

How to install BlueMap (step by step)

Install the plugin or mod, start the server once, set accept-download: true in core.conf, set the port in webserver.conf and reload BlueMap. In detail:

1. Put the BlueMap file on the server. Plugin: drop the .jar into plugins/. Mod: drop it into mods/.

2. Start (or restart) the server once. BlueMap creates its config folder and writes a message to the console that it needs your permission to download resources. At this point it doesn't render anything yet – this is normal.

3. Accept the download in core.conf. Open plugins/BlueMap/core.conf (mods: config/bluemap/core.conf) and change:

   accept-download: false
   

   to:

   accept-download: true
   

   BlueMap needs textures and models from the official Minecraft client to draw the world, and it downloads them from Mojang only after you agree. Without this change the map stays empty.

4. Set the web server port in webserver.conf. In the same folder, find port: 8100 and change it to the port you're allowed to use (on a hosted server: the port your host gave you for the map). On a home server you can keep 8100.

5. Reload BlueMap. Type bluemap reload in the server console (or /bluemap reload in game as an operator) – or simply restart the server.

6. Open the map in your browser at http://your-server-address:port, for example http://play.example.com:8100.

Rendering starts automatically after the reload. Type bluemap in the console to see the status and progress of the render.

Which port does BlueMap use?

By default BlueMap's web server listens on port 8100 (TCP); you change it with the port setting in webserver.conf. The port is separate from the game port (25565 by default) – the map is a website, and the game and the map can't share one port.

• On a hosted server you can usually only use the ports your host assigned to your server. Port 8100 is almost never one of them, so set BlueMap to the port you were given – otherwise the map runs but nobody can reach it.
• On a home server forward the BlueMap port (TCP) on your router to the PC running the server, the same way as the game port, and allow Java in your firewall.
• One port, one web server. If another add-on with its own web server (for example Dynmap) uses the same port, one of them fails to start. Give each a different port.

How do I open the BlueMap map in a browser?

Type http://, your server's address, a colon and the BlueMap port into the browser's address bar – for example http://play.example.com:8100. Use the address without the game port: the part after the colon must be the map port.

• Type http:// explicitly. Many browsers try https:// first, and BlueMap's built-in web server doesn't do HTTPS on its own, so the page won't load.
• Share the same link with your players – they don't need to install anything, and they don't even need to own Minecraft to look at the map.
• You can add the link to your server's Discord, website or MOTD.

How long does BlueMap take to render?

The first render can take from a few minutes to many hours – it depends on how many chunks the world has and how much CPU the server can spare. BlueMap renders only chunks that already exist (that someone has explored or that you pre-generated), and it shows finished parts of the map while it works, so you'll see the world appear tile by tile.

• After the first render BlueMap only updates the parts of the world that change, so later updates are fast.
• CPU. Rendering uses the server's processor. On a small server lower the number of render threads with render-thread-count in core.conf (for example to 1) so players don't notice lag while it renders.
• Disk space. The rendered map is stored as files inside the server folder (by default in bluemap/web/maps). In our own test a vanilla area of 1024 × 1024 blocks took about 90 MB of map files – a big, explored world can need several gigabytes.
• Nether and End. By default BlueMap creates a map for each dimension (Overworld, Nether, End), each with its own file in the maps folder. If you only want the Overworld, disable the others to save CPU and disk.

To render a bigger area before players explore it, pre-generate the world with a plugin such as Chunky – BlueMap then renders the generated chunks.

BlueMap not working? Common problems and fixes

Most "BlueMap not working" cases come down to four things: accept-download still false, the wrong port, https:// in the browser, or a render that simply hasn't finished. Check them in this order.

If the console shows a long Java error mentioning BlueMap right after the start, the BlueMap version usually doesn't match your Minecraft version or loader. Install the build made for your exact version.

How to set up BlueMap on a Spot.gg server

On Spot.gg every Minecraft Java server already has its own port reserved for a map – you install BlueMap from the "Addons" tab, set that port in webserver.conf and open the map at your server's address with that port. You don't need router settings or port forwarding.

1. Find your map port

Open "Network" in the server menu. In the "Ports" table there is a row named "Map" with the description "For BlueMap, Dynmap or squaremap". That number is the port for BlueMap – copy it with the "Copy" button. Leave the other ports alone: the "Game" port is for players joining, and the "Voice chat" port is for voice chat plugins.

Velocity proxy servers don't have a map port, because BlueMap has no Velocity version – install it on the Paper or Fabric servers behind the proxy instead.

2. Install the BlueMap plugin

1. Go to "Addons" → "Available to install" and search for BlueMap.
2. Open it, choose the version for your Minecraft version and click "Install", then confirm with "Install".
3. If the server is running, the panel asks whether to restart it now – click "Restart".

The BlueMap plugin in our catalog runs on the Paper and Purpur engines – you can also look at it on the BlueMap plugin page. On a Vanilla server, the "Addons" tab says the engine doesn't support mods or plugins: go to "Information" → "Modify" → "Change engine" and pick Paper in the same Minecraft version – the world and settings are preserved. On Fabric, Forge or NeoForge, download the BlueMap mod for your loader and version and upload it to the mods folder in "Files" – click "Click to upload" or drag the file onto the page.

3. Edit core.conf and webserver.conf

1. In "Files" open plugins/BlueMap/ (mods: config/bluemap/). The folder appears after the first start with BlueMap.
2. Click "Edit" next to core.conf, change accept-download: false to accept-download: true and click "Save". While you're there, you can set render-thread-count: 1 so rendering doesn't slow down the game.
3. Click "Edit" next to webserver.conf, change port: 8100 to your "Map" port from "Network" and click "Save".
4. In "Console" type bluemap reload, or restart the server with the button at the top of the panel.

4. Open the map

Take your server address from "Network" and add the map port after a colon:

• with the "Custom address": http://yourname.spot.gs:MAPPORT
• with the "Basic address": replace the game port after the colon with the map port, e.g. http://sID-xxxxx.spot.gs:MAPPORT

Type it with http:// – the map is served over plain HTTP, not HTTPS. Then share the link with your players.

Keep in mind that the map files count towards your server's disk space, and the first render uses part of your server's CPU. You can try BlueMap on a free server for 24 hours; paid servers start from $3.90 per month.

BlueMap vs Dynmap vs squaremap

BlueMap is the choice if you want a 3D map; Dynmap and squaremap draw flat maps and are lighter. All three run a web map from your server and on Spot.gg use the same "Map" port.

Run only one map add-on at a time – two web servers on one port won't both work.

FAQ

Is BlueMap free?

Yes. BlueMap is free and open source. You install it as a plugin or mod on your server; players open the map in a browser without paying or installing anything.

What is the default BlueMap port?

8100 (TCP). You change it with port in webserver.conf. On a hosted server use the port your host assigned for the map – on Spot.gg it is the "Map" port in "Network".

Why does BlueMap ask me to accept a download?

BlueMap needs textures and models from the official Minecraft client to render the world and downloads them from Mojang. It only does that after you set accept-download: true in core.conf; until then the map stays empty.

Can I use BlueMap on a Vanilla server?

Not as an add-on, because Vanilla doesn't load plugins or mods. Switch the server to Paper or Purpur (or Fabric for mods) and install BlueMap there. On Spot.gg you can change the engine in the same Minecraft version and keep the world.

Does BlueMap work with Bedrock Edition?

No. BlueMap only reads Minecraft Java worlds. A Bedrock server can't run it.

Do players need to install anything to see the map?

No. The map is a website. Anyone with the link can open it in a browser, even without Minecraft.

Can BlueMap use HTTPS?

Not on its own – the built-in web server serves plain HTTP, so open the map with http://. HTTPS needs a separate reverse proxy with a certificate in front of BlueMap.

How do I reload BlueMap after changing the config?

Type bluemap reload in the server console, or /bluemap reload in game as an operator. Restarting the server also works.