Running Metabase from the JAR File

Metabase is an open-source business intelligence tool, and the quickest way to run it on your own machine is the self-contained JAR. No installer, no Docker, just Java and a single file. This tutorial covers downloading the JAR, running it, and the common issues you may hit on the first launch.

Step 1: Install Java

The Metabase JAR needs a Java runtime. A current build requires Java 21 or higher (older Metabase versions ran on Java 8 or 11). It works with both OpenJDK and Oracle JDK. Check what you have:

java -version

If Java is missing or too old, install a JDK. On macOS with Homebrew:

brew install openjdk@21

On Debian or Ubuntu, sudo apt install openjdk-21-jre works. Always confirm the required version on the official download page, since it changes between Metabase releases.

Step 2: Download the JAR

Download metabase.jar from the official Metabase site (metabase.com/start/oss/jar) and put it in a folder of its own, because Metabase will create files next to it on first run.

Step 3: Run it

From the folder containing the file, start Metabase:

java -jar metabase.jar

It will log startup progress to the terminal, initialise its application database, and then report that it is ready. Open http://localhost:3000 in your browser and complete the one-time setup wizard.

Step 4: Choose where Metabase stores its data

By default Metabase creates an embedded H2 database (metabase.db.mv.db) in the working directory. That is fine for trying it out, but H2 is not recommended for production. To use a different port or a proper application database such as PostgreSQL, set environment variables before launching:

# Change the port
MB_JETTY_PORT=3001 java -jar metabase.jar

# Use Postgres as the application database
export MB_DB_TYPE=postgres
export MB_DB_DBNAME=metabaseappdb
export MB_DB_PORT=5432
export MB_DB_USER=metabase
export MB_DB_PASS=yourpassword
export MB_DB_HOST=localhost
java -jar metabase.jar

Common issues

• Wrong Java version: an error like UnsupportedClassVersionError means your Java is older than the JAR requires. Install the version listed on the download page.
• Port already in use: if 3000 is taken, set MB_JETTY_PORT to another port as shown above.
• Out of memory: give the JVM more heap with java -Xmx2g -jar metabase.jar.
• Run it in the background: on a server, keep it alive with nohup java -jar metabase.jar > metabase.log 2>&1 &, or wrap it in a systemd service.

Summary

Running Metabase from the JAR is just java -jar metabase.jar once a compatible Java is installed. For anything beyond a quick trial, move it off the default H2 database onto PostgreSQL and run it as a managed background service.