ANT_OPTS in Apache Ant: JVM Memory, Proxy Settings, and Startup Troubleshooting

Apache Ant can be tuned before any build runs by setting environment variables. This guide is for build and DevOps engineers who want predictable Ant behavior across local machines and CI runners, and it covers exactly how ANT_OPTS, ANT_ARGS, and JAVACMD are used.

Originally published on 2010-04-14; fully revised and updated.

Source context: Usage of ANT_OPTS in Ant Script | ANT_OPTS capabilities.

What ANT_OPTS, ANT_ARGS, and JAVACMD do

Ant launcher scripts read environment variables and then start Java + Ant with those settings. The most useful variables are shown below.

Runtime flow when you execute an Ant build

This is the high-level startup path that explains where each variable is applied.

flowchart TD
    A[Set ANT_OPTS ANT_ARGS JAVACMD] --> B[Run ant command]
    B --> C[Launcher script selects Java binary]
    C --> D[Start JVM with ANT_OPTS]
    D --> E[Ant reads ANT_ARGS and CLI args]
    E --> F{Arguments valid}
    F -- no --> G[Startup error and exit]
    F -- yes --> H[Execute requested target]

Common ANT_OPTS use cases

Set JVM heap for larger builds

If dependency resolution, compilation, or large XML processing causes memory pressure, increase heap via ANT_OPTS.

# Windows CMD
set ANT_OPTS=-Xms256m -Xmx1024m
ant clean compile

# Linux/macOS shell
export ANT_OPTS="-Xms256m -Xmx1024m"
ant clean compileCode language: PHP (php)

Pass JVM system properties into Ant builds

A common pattern is passing build-time properties through the JVM so the Ant build file can consume them.

# Windows CMD
set ANT_OPTS=-Dlog.dir=C:\logs
ant run

# Linux/macOS shell
export ANT_OPTS="-Dlog.dir=/var/log/myapp"
ant runCode language: PHP (php)

<project name="demo" default="show-log-dir">
  <target name="show-log-dir">
    <echo>Log directory is set to: ${log.dir}</echo>
  </target>
</project>Code language: HTML, XML (xml)

Configure proxy settings for dependency downloads

You can pass HTTP/HTTPS proxy host and port as JVM properties when Ant must reach external repositories through a corporate proxy.

# Windows CMD
set ANT_OPTS=-Dhttp.proxyHost=myproxy -Dhttp.proxyPort=3128 -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=3128
ant mytarget

# Linux/macOS shell
export ANT_OPTS="-Dhttp.proxyHost=myproxy -Dhttp.proxyPort=3128 -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=3128"
ant mytargetCode language: PHP (php)

Troubleshooting invalid ANT_OPTS values

If ANT_OPTS contains invalid JVM arguments, Ant may fail before your build starts.

• Symptom 1: Unrecognized option and JVM startup failure.
• Symptom 2: NoClassDefFoundError if a malformed token is interpreted as a class name.
• Check: Print the current variable and confirm every token is a valid JVM option.
• Fix: Correct or clear ANT_OPTS and run Ant again.

# Inspect current value
# Windows CMD
echo %ANT_OPTS%

# Linux/macOS shell
echo "$ANT_OPTS"

# Clear and retest
# Windows CMD
set ANT_OPTS=
ant -version

# Linux/macOS shell
unset ANT_OPTS
ant -versionCode language: PHP (php)

Unrecognized option: -3
Could not create the Java virtual machine.

Exception in thread "main" java.lang.NoClassDefFoundError: error-stringCode language: CSS (css)

Best practices and common pitfalls

• Use ANT_OPTS only for JVM flags (memory, -D properties, GC/JVM options).
• Use ANT_ARGS for repeated Ant CLI flags, not JVM flags.
• Use JAVACMD when you must pin Ant to a specific Java binary.
• Avoid storing proxy credentials in plain text environment variables when possible; prefer CI secret management.
• Document team-standard settings in build scripts or CI configuration to reduce machine-to-machine drift.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.