What is package-info.java in Java

package-info.java is a special source file that lives in a Java package directory. It has two primary purposes: adding Javadoc documentation at the package level, and applying annotations to an entire package at once. It's optional, but it becomes increasingly valuable as codebases grow.

File Location and Structure

The file must be placed directly inside the package directory it describes — one file per package. It contains a package declaration, optionally preceded by a Javadoc comment and/or annotations:

/**
 * Provides utility classes for parsing and validating user input.
 *
 * <p>All classes in this package are thread-safe unless stated otherwise.
 * The primary entry point is {@link com.myapp.util.InputParser}.
 */
package com.myapp.util;

That's the entire file. No class declaration, no imports (unless needed for annotations). The package statement must be the only top-level declaration.

Use Case 1: Package-Level Javadoc

When you run javadoc, the comment in package-info.java becomes the description for that package in the generated HTML documentation. Without this file, the package page has no description.

A well-written package comment typically includes:

• What the package is for (one sentence)
• The main entry-point class(es) a new user should look at first
• Any thread-safety guarantees or invariants that apply across the package
• Links to related packages with {@link}

/**
 * Contains the HTTP client abstraction layer.
 *
 * <p>Use {@link com.myapp.http.HttpClient} as the primary entry point.
 * All implementations in this package are non-blocking by default.
 *
 * @see com.myapp.auth Authentication utilities used by this package
 */
package com.myapp.http;

Use Case 2: Package-Level Annotations

Annotations placed in package-info.java apply to the entire package. A common use is marking an entire package as deprecated when you're retiring a legacy API:

@Deprecated(since = "2.0", forRemoval = true)
package com.myapp.legacy;

This causes IDEs and javac to show a deprecation warning for any code that imports from com.myapp.legacy.

Another common use is suppressing warnings across an entire package:

@SuppressWarnings("deprecation")
package com.myapp.migration;

Null Safety Annotations (JetBrains, Checker Framework)

Many teams use package-info.java to set a default null-safety policy for all classes in the package. For example, with JetBrains annotations:

@org.jetbrains.annotations.NonNullApi
package com.myapp.service;

Or with the Checker Framework's @DefaultQualifier. This marks every method parameter and return type in the package as non-null by default, so you only need to annotate the exceptions with @Nullable. It's much less verbose than annotating every individual element.

Rules and Constraints

• Exactly one package-info.java per package — you can't have two
• The file must be in the same directory as the package's other .java files
• No class, interface, or enum declarations allowed in this file
• Import statements are allowed (required if annotations need them)
• The file compiles to package-info.class — it's a real compilation artifact

package-info.java vs package.html

Before Java 5, the older way to document packages was a file called package.html — plain HTML that Javadoc would read. package-info.java replaced it:

If your codebase has package.html files, they still work but you should migrate them to package-info.java to gain annotation support.

Generating Javadoc

Run the standard javadoc command — package-info.java is automatically picked up:

javadoc -d docs/ -sourcepath src/ com.myapp.util

Or with Maven:

mvn javadoc:javadoc

The package description appears at the top of the package's summary page in the generated documentation.

Summary

package-info.java serves two purposes: providing Javadoc for an entire package, and applying annotations to all classes in the package at once. It's optional for small projects but becomes valuable in larger codebases — especially for marking deprecated packages, setting default null-safety policies, and giving new developers a clear orientation to each package's purpose. One file per package, placed in the package's source directory.