skip to content

How do you set a JVM system property for a Gradle build without using -D on the command line?

level: middleimportance: should knowfreq 45%

answer

  1. systemProp.x in gradle.properties
  2. persistent equivalent of -Dx
  3. system-property namespace
  4. no env-var convention for system props
  5. proxy / TLS / plugin config

basics

~10 s

Put systemProp.name=value in a gradle.properties file. Gradle strips the systemProp. prefix and sets name as a JVM system property — the persistent equivalent of -Dname=value.

solid answer

~40 s

The `systemProp.` prefix in a `gradle.properties` file declares a **JVM system property**: `systemProp.http.proxyHost=proxy.corp` becomes `http.proxyHost` in the system-property table, exactly as `-Dhttp.proxyHost=proxy.corp` would on the command line. This is the durable, checked-in (or per-user) way to set system properties such as proxy settings, TLS config, or a property a plugin reads, without repeating `-D` on every invocation. It mirrors the project-property story: `ORG_GRADLE_PROJECT_x` (env var) and `-Px` (CLI) feed the project-property namespace, while `systemProp.x` (gradle.properties) and `-Dx` (CLI) feed the system-property namespace. Read these with `System.getProperty("x")` or `providers.systemProperty("x")`. Note the asymmetry: there is no `ORG_GRADLE_PROJECT_`-style env-var convention for system properties — `systemProp.` lives only in gradle.properties.

code

toml · 4 lines
toml
# ~/.gradle/gradle.properties (rendered as properties)
systemProp.http.proxyHost=proxy.corp.example
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.corp.example

go deeper

for a junior

Know that systemProp.name in gradle.properties sets a JVM system property, like -Dname.

for a middle

Place it correctly in the four-quadrant map (CLI/env/properties × project/system) and name a real use like proxy config.

for a senior

Explain persistence vs CLI trade-offs and the lack of an env-var convention for system properties, plus the forked-JVM caveat.

for a principal

Set policy on where shared system-property defaults live (~/.gradle vs project) and keep secrets out of checked-in gradle.properties.

## The systemProp. convention Inside a `gradle.properties` file (project-level or in `~/.gradle/`), any line prefixed with `systemProp.` declares a JVM system property: ```properties systemProp.http.proxyHost=proxy.corp.example systemProp.http.proxyPort=8080 systemProp.javax.net.ssl.trustStore=/etc/certs/ca.jks ``` Gradle strips the `systemProp.` prefix and installs the remainder into the system-property table of the build JVM. The effect is identical to passing `-Dhttp.proxyHost=proxy.corp.example` on the command line, but it is persistent and need not be retyped. ## The full four-quadrant picture | | Project property | System property | |----------------|-------------------------|----------------------------| | Command line | `-Px=v` | `-Dx=v` | | Env variable | `ORG_GRADLE_PROJECT_x` | *(no env convention)* | | gradle.properties | `x=v` | `systemProp.x=v` | Read project properties with `findProperty` / `providers.gradleProperty`; read system properties with `System.getProperty` / `providers.systemProperty`. The two columns are separate tables and never cross-populate. ## Why use systemProp. instead of -D - **Persistence:** proxy/TLS settings belong in `~/.gradle/gradle.properties` so every build on the machine picks them up. - **Team defaults:** a checked-in project `gradle.properties` can carry shared system-property defaults (non-secret). - **Cleaner commands:** avoids long, error-prone `-D...` chains on every run. ## The forked-JVM caveat still applies A `systemProp.` value lives on the **build/daemon JVM**. A forked `Test` JVM does not inherit it automatically; forward it with `systemProperty(...)` in the `test {}` block if your tests need it. The persistence convention does not change the inheritance behavior. ## Reading it the configuration-cache-friendly way ```kotlin val proxy = providers.systemProperty("http.proxyHost").orNull ```

  • What is the command-line equivalent of systemProp.http.proxyHost=proxy in gradle.properties?
    -Dhttp.proxyHost=proxy. Both set the same JVM system property; gradle.properties just makes it persistent.
  • Is there an env-var convention for system properties like ORG_GRADLE_PROJECT_ is for project properties?
    No. ORG_GRADLE_PROJECT_ maps only to project properties. System properties come from -D or the systemProp. prefix in gradle.properties.

saying these in an interview costs you the question

  • Confusing systemProp.x (system property) with a plain x= entry (project property) in gradle.properties.
  • Claiming systemProp. values are read via findProperty.
  • Believing there's an ORG_GRADLE_PROJECT_-style env variable for system properties.

context

resolving links…