🌱🔐 Spring-Dotenv

January 2, 2026 · View on GitHub

What this library does

Spring-Dotenv integrates the excellent dotenv-java library into the Spring ecosystem by exposing .env files as a Spring PropertySource.

It lets you:

Load environment variables from a local .env file during development
Keep production behavior unchanged (real environment variables always win because .env values are added after system environment variables, preserving standard Spring precedence)
Follow The Twelve-Factor App principle of configuration via environment

The .env file is strictly a development convenience. It should never be committed to source control.

📄 See the CHANGELOG.md for breaking changes, upgrades, and release notes.

Requirements

Java 17 or newer
Spring Framework or Spring Boot 3 / 4

If you need Java 8 or 11 support, use an older release.

Modules

This project is published as multiple artifacts. Choose exactly one at runtime.

spring-dotenv
Core library for Spring Framework (no Spring Boot auto-integration)
springboot3-dotenv
Auto-integrates with Spring Boot 3
springboot4-dotenv
Auto-integrates with Spring Boot 4

A BOM is provided to keep versions aligned across modules.

Installation

Recommended (BOM-based)

Gradle

dependencies {
    implementation(platform("me.paulschwarz:spring-dotenv-bom:$version"))
    developmentOnly("me.paulschwarz:springboot4-dotenv")
}

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>me.paulschwarz</groupId>
            <artifactId>spring-dotenv-bom</artifactId>
            <version>$version</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>me.paulschwarz</groupId>
        <artifactId>springboot4-dotenv</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

First-time set up

Add .env to your .gitignore:

.env

It’s common to commit a .env.example file instead, documenting the available variables without leaking secrets.

Usage

Assume a simple Spring application that needs a configurable value:


@Value("${example.name}")
String name;

Declare the property in application.yml:

example:
  name: ${EXAMPLE_NAME:World}

Create a local .env file:

EXAMPLE_NAME=Paul

At runtime:

If EXAMPLE_NAME is set in the real environment, that value wins
Otherwise, the value from .env is used
If neither is present, the default (World) applies

This preserves production safety while making local development frictionless.

Keys loaded from .env participate in relaxed name resolution when running under Spring Boot (3 or 4). In plain Spring Framework applications, .env keys are resolved strictly.

For example, under Spring Boot:

MY_SERVICE_URL=https://example.com

can be accessed as:

my.service.url

Configuration (optional)

All configuration is optional. Defaults are sensible.

Spring Framework vs Spring Boot

Spring Boot 3 / 4
- Relaxed binding is applied to:
  - springdotenv.* configuration keys
  - variables defined inside .env files
- Standard Spring Boot rules apply (kebab-case, camelCase, uppercase environment variables).
Plain Spring Framework
- Configuration is strict:
  - springdotenv.* keys must match exactly
  - .env entries must match exactly
- No relaxed binding is applied.

System property	Environment variable	Default value
`springdotenv.enabled`	`SPRINGDOTENV_ENABLED`	`true`
`springdotenv.directory`	`SPRINGDOTENV_DIRECTORY`
`springdotenv.filename`	`SPRINGDOTENV_FILENAME`	`.env`
`springdotenv.ignoreIfMalformed`	`SPRINGDOTENV_IGNORE_IF_MALFORMED`	`false`
`springdotenv.ignoreIfMissing`	`SPRINGDOTENV_IGNORE_IF_MISSING`	`true`
`springdotenv.exportToSystemProperties`	`SPRINGDOTENV_EXPORT_TO_SYSTEM_PROPERTIES`	`false`

⚠️ Binding semantics note
The keys shown above support relaxed binding only in Spring Boot applications.
When using the core spring-dotenv module without Spring Boot, these keys must be specified exactly.

Notable options

springdotenv.enabled
Defaults to true. Set to false to completely disable integration.
springdotenv.exportToSystemProperties
If enabled, variables loaded from .env are also exported to System.getProperties().
This field was previously known as systemProperties but was renamed for clarity. It is deprecated but still supported with warning.
If both the legacy and the canonical property are set, the canonical key (springdotenv.exportToSystemProperties) takes precedence.
When exportToSystemProperties is enabled, .env variables are exported verbatim. Relaxed name resolution is applied only when values are read via Spring’s Environment.
springdotenv.ignoreIfMissing
Defaults to true. Set to false to fail fast when .env is absent.

Notes on prefixes

Older versions required properties to be prefixed (for example env.EXAMPLE_NAME).

This is no longer the case. Prefixes have been removed.

Configuration binding semantics

Spring-Dotenv follows the configuration rules of the runtime it integrates with.

Spring Boot applications

When used with Spring Boot 3 or 4, all springdotenv.* configuration options and .env file entries participate in standard Spring Boot relaxed binding.

This means configuration keys are interchangeable across common naming styles:

springdotenv.ignore-if-missing
springdotenv.ignoreIfMissing
SPRINGDOTENV_IGNORE_IF_MISSING

Likewise, variables defined in .env files are resolved using the same relaxed rules when accessed through the Spring Environment. For example:

MY_SERVICE_URL=https://example.com

can be consumed as:

my.service.url

This behavior is delegated to Spring Boot’s native Binder and matches Boot’s built-in configuration semantics.

Spring Framework (non-Boot) applications

When using the core spring-dotenv module without Spring Boot, all configuration is strict:

springdotenv.* keys must match exactly
.env entries are resolved by exact name only
No relaxed binding or env-var style name conversion is applied

This distinction is intentional and mirrors the behavior of Spring Framework itself.

Building locally

./gradlew build

Contributing

Pull requests are welcome.

For substantial changes, please open an issue first to discuss scope and approach. Tests are expected for behavioral changes.