Tomcat memory settings: where to put -Xmx

JAVA_OPTS or CATALINA_OPTS?

JAVA_OPTS is read by every Tomcat command, including shutdown and the version script. CATALINA_OPTS is read only when Tomcat starts. Put heap and GC settings in CATALINA_OPTS so a stop command does not start a second JVM with a big heap.

Package install on Debian or Ubuntu

Edit /etc/default/tomcat10 and replace the JAVA_OPTS line:

JAVA_OPTS="-Djava.awt.headless=true -Xms512m -Xmx512m -XX:MaxMetaspaceSize=192m"

Restart with sudo systemctl restart tomcat10. On Rocky and Alma, edit /etc/tomcat/tomcat.conf instead.

Tarball install

Create bin/setenv.sh in the Tomcat directory. Tomcat runs it automatically if it exists:

sudo tee /opt/tomcat/bin/setenv.sh >/dev/null <<'EOF'
CATALINA_OPTS="-Xms512m -Xmx512m -XX:MaxMetaspaceSize=192m"
EOF
sudo chmod +x /opt/tomcat/bin/setenv.sh
sudo systemctl restart tomcat

Systemd drop-in (works for both)

sudo systemctl edit tomcat10
# add:
[Service]
Environment="CATALINA_OPTS=-Xms512m -Xmx512m"

Drop-ins survive package upgrades, which edits to the shipped unit file do not.

What to put in the numbers

Do not give the heap all of the RAM. A 1 GB server cannot have -Xmx1g: metaspace, thread stacks and the OS need room too. Use the JVM heap calculator or read how much RAM a Java app needs. A reasonable first guess is 55 to 60 percent of RAM for the heap on a server with only Tomcat, and about 45 percent if a database runs on the same machine. Setting -Xms equal to -Xmx avoids heap resizing pauses.

Confirm it took effect

PID=$(pgrep -f catalina | head -1)
sudo -u tomcat jcmd $PID VM.flags | tr ' ' '\n' | grep -E "MaxHeapSize|InitialHeapSize|Metaspace"
ps -o args= -p $PID | tr ' ' '\n' | grep -E "^-X"

MaxHeapSize is shown in bytes. 536870912 equals 512 MB. If the number is not what you set, the option is in the wrong file for your install type.

Last updated October 29, 2026.