Why does adding -Xshare:off allow NetLogo to run in headless mode?

isaacalexis64 · June 20, 2026, 8:53pm

Hi everyone,

I was trying to run NetLogo in headless mode and was unable to get it working. After troubleshooting with ChatGPT, I was advised to modify the JVM options by adding -Xshare:off.

Originally, I had:

JVM_OPTS=(
  -XX:MaxRAMPercentage=50
  -Dfile.encoding=UTF-8
  -Dnetlogo.extensions.dir="${BASE_DIR}/extensions"
  -Dnetlogo.models.dir="${BASE_DIR}/models"
  --add-exports=java.base/java.lang=ALL-UNNAMED
  --add-exports=java.desktop/sun.awt=ALL-UNNAMED
  --add-exports=java.desktop/sun.java2d=ALL-UNNAMED
)

After changing it to:

JVM_OPTS=(
  -Xshare:off
  -XX:MaxRAMPercentage=50
  -Dfile.encoding=UTF-8
  -Dnetlogo.extensions.dir="${BASE_DIR}/extensions"
  -Dnetlogo.models.dir="${BASE_DIR}/models"
  --add-exports=java.base/java.lang=ALL-UNNAMED
  --add-exports=java.desktop/sun.awt=ALL-UNNAMED
  --add-exports=java.desktop/sun.java2d=ALL-UNNAMED
)

NetLogo started working correctly in headless mode.

My question is: why would adding -Xshare:off fix the issue?

For context:

NetLogo version: 6.4.0
Java version: jdk 25
OS: Debian
Environment: On-premise

Any insight into the underlying cause would be appreciated.

Thanks!

ERSUCC · June 21, 2026, 8:22am

Hi Isaac,

I’ve never seen this option used before, but my best guess without seeing any logs or error messages is that something is going wrong because you’re using Java 25. NetLogo 6.4.0 was created and bundled with Java 17, so I definitely wouldn’t expect everything to go smoothly if you’re trying to launch it with Java 25.

Are you aware that there is a netlogo-headless.sh script bundled with NetLogo that does all the necessary setup for you and uses the correct bundled version of Java? If you weren’t aware of that script, I would recommend starting there. If I misunderstood and you’re already using that script, then it would be helpful if you could send any error messages you saw while trying to get it working.

Also, it is worth noting that the latest release of NetLogo is 7.0.4, which can be found here. Regardless of any of my points above, you’re more likely to have a good experience if you use the latest version of NetLogo.

Isaac B.