PROPERTIES File Documentation

Summary

A Java Properties File (.properties) is a plain-text configuration file that stores settings as simple key=value pairs, read and written by Java’s java.util.Properties class since 1996. It is used for application config (Spring’s application.properties) and for translation bundles. Being plain text with the MIME type text/plain, it opens in any code editor — VS Code or Notepad++ on Windows, TextEdit on Mac, vim on Linux. Back up the file before editing, since one bad value can stop the app from starting.

Technical details

FeatureValue
Full nameJava Properties File
File extension.properties
MIME typetext/plain
Format typePlain-text key/value configuration
DeveloperSun Microsystems / Oracle (Java platform)
CategorySettings file
Introduced1996 (Java 1.0, java.util.Properties)
Default encodingISO‑8859‑1 (Latin‑1); UTF‑8 readable since Java 9
Open standardYes — format documented in the Java API
Key/value separator=, :, or whitespace
Comment markers# or ! at the start of a line
Line continuationTrailing backslash \
Unicode escapes\uXXXX for non‑Latin‑1 characters
XML variantstoreToXML() / loadFromXML()
Common usesApp config (application.properties), i18n (ResourceBundle)
Related extensions.ini, .cfg, .conf, .xml, .yaml, .env
Specificationdocs.oracle.com/.../java/util/Properties.html
Syntax at a glance

A .properties file is plain text with no signature. Each line is one setting written as key=value (the separator may also be : or whitespace). Lines starting with # or ! are comments. A trailing backslash \ continues a value onto the next line. By specification the file is read as ISO‑8859‑1, so characters outside Latin‑1 are stored as \uXXXX escapes (for example café for “café”). Keys use dotted names by convention (server.port) to group settings, but there is no real nesting — every value is a string the application interprets itself.

What is a properties file?

A .properties file is the standard configuration format of the Java platform, read and written by the java.util.Properties class since Java 1.0 in 1996. It stores settings as a flat list of key=value pairs in plain text, and it was designed to be minimal: no data types, no nesting, and no schema. Every value is a string, and the application that loads the file decides what each string means. That simplicity is why the format has survived essentially unchanged for nearly three decades and why it appears throughout Java and Spring projects.

Two uses dominate. The first is application configuration: database URLs, ports, timeouts and feature flags, most visibly Spring Boot’s application.properties. The second is internationalisation, where java.util.ResourceBundle loads a family of files like messages_en.properties and messages_fr.properties to supply translated interface strings. Developers, testers and translators typically meet a .properties file inside a Java project’s source tree, bundled inside a .jar or .war archive, or in a server’s install folder when they need to change a setting.

The line syntax: keys, separators and comments

The parser reads the file line by line. A line that is blank or begins (after optional leading whitespace) with # or ! is a comment and is ignored. Any other line is a key/value entry. The key is the text up to the first unescaped separator, and the separator may be an equals sign, a colon, or whitespace — all three of the following set the same property:

server.port=8080
server.port : 8080
server.port   8080

Whitespace around the separator is dropped, so key = value and key=value are identical. Because the separator characters and whitespace are significant, a literal =, :, space, # or ! inside a key must be escaped with a backslash. Everything after the separator, up to the end of the (possibly continued) line, is the value, and leading whitespace on the value side is stripped while trailing whitespace is kept.

Line continuation and backslash escapes

A backslash at the very end of a line continues the value onto the next line, and leading whitespace on the continuation line is discarded, so a long value can be wrapped for readability:

welcome.message=Hello, \
                and welcome to the app
# parsed as: "Hello, and welcome to the app"

Within a value the parser recognises the usual backslash escapes: \n, \r, \t, \f, a literal \\, and the escaped separators above. The most consequential escape is \uXXXX, a four-hex-digit Unicode code point, which exists because of the file’s encoding rule described next.

The ISO-8859-1 encoding rule and \uXXXX

By specification, a classic .properties file is read as ISO‑8859‑1 (Latin‑1). Any character outside that single-byte range cannot be stored directly and is instead written as a \uXXXX Unicode escape. This is why accented or non-Latin text in a properties file often appears as codes rather than letters: the string “café” is stored as café, and a Japanese label becomes a run of \u escapes. The escapes are correct, and a properties-aware editor or the running application decodes them back to real characters. The JDK historically shipped a native2ascii tool precisely to convert UTF-8 source into this escaped ISO‑8859‑1 form.

Since Java 9 (2017) the Properties API can also read a properties file as UTF‑8 directly, and many modern tools write UTF‑8 without escapes. But the ISO‑8859‑1 default is still the safe assumption for a file of unknown origin, and saving a file as UTF‑8 where the consuming application expects Latin‑1 is a common way to mangle accented characters. There is also an XML-based variant of the format: Properties.storeToXML() writes the same logical key/value model as an XML document, and loadFromXML() reads it back.

Dotted keys and the illusion of nesting

The format has no hierarchy, but a naming convention simulates one. Keys such as spring.datasource.url and spring.datasource.username share a dotted prefix so that related settings read as a group, and frameworks like Spring bind such keys onto nested configuration objects. At the file level, though, each of these is an independent, flat entry: the dots are ordinary characters in the key string, not structure the parser understands. This is the key practical difference from YAML, where indentation expresses real nesting. Spring Boot accepts both application.properties and application.yml for exactly the same settings, and flat dotted keys map onto the nested YAML form.

Frequently asked questions

Why does my .properties file show A-style codes instead of letters?

By the Java specification the file is read as ISO‑8859‑1, so characters outside Latin‑1 are stored as \uXXXX Unicode escapes. They are correct: a properties-aware editor or the running application decodes them back to real characters.

What program creates .properties files?

Java applications, through the java.util.Properties class. They are everywhere in Java and Spring projects (application.properties) and for translations (ResourceBundle files like messages_en.properties).

What is the difference between .properties and .yml in Spring Boot?

Both configure the same app. .properties is flat key=value (server.port=8080); a .yml file is nested YAML (server: then an indented port: 8080). Spring reads either; YAML is usually preferred for hierarchical or list settings.

Where is application.properties located?

In a Spring Boot project it is usually under src/main/resources in the source tree and bundled inside the JAR or WAR at runtime. You can override it with an external file next to the JAR or via the spring.config.location setting.

References