Packages

A package is a namespace that groups related classes, interfaces, and sub-packages together. As a codebase grows from a handful of files to thousands, packages are what keep names from colliding and let you organize code by feature, layer, or team ownership — much like folders organize files on disk.

Declaring a Package

A file declares which package it belongs to with a package statement. This must be the very first non-comment line in the file — before any imports or class declarations.

src/com/example/myapp/OrderProcessor.java

Java

package com.example.myapp;

public class OrderProcessor {
    public void process() {
        System.out.println("Processing order...");
    }
}

Every class in that file now belongs to the com.example.myapp package. Other code refers to this class by its fully-qualified name, com.example.myapp.OrderProcessor, unless it imports it first.

Naming Convention: Reverse Domain Name

By convention, package names start with the reversed segments of a domain name the organization controls — for example, example.com becomes com.example, followed by the project and feature area, such as com.example.myapp.orders.

Note

This convention exists to guarantee global uniqueness. Domain names are already unique worldwide, so reversing one into a package prefix means two companies can never accidentally publish classes with colliding package names, even if they both happen to name a class Order or User.

Directory Structure Must Mirror the Package

The Java compiler and JVM expect a package's directory layout on disk to exactly match its dotted name. Each dot in the package name corresponds to one directory level.

Package com.example.myapp on disk

Text

src/
└── com/
    └── example/
        └── myapp/
            ├── OrderProcessor.java
            └── OrderProcessor.class

Warning

If the directory structure does not match the declared package — for example, placing OrderProcessor.java directly under src/ while it declares package com.example.myapp; — you will get a compile error, or in some build tools a class-not-found error at runtime even though the file compiled. This mismatch is one of the most common causes of "it compiles on my machine but not in the build" problems for Java beginners.

The Default (Unnamed) Package

If a file has no package statement at all, its classes belong to the default, unnamed package. This is fine for a quick throwaway script or a single-file learning exercise.

Note

For any real project, avoid the default package. Classes in it cannot be imported by name from other packages, it does not scale past a handful of files, and virtually every build tool, IDE, and style guide assumes real code lives inside a properly named package.

Why Packages Matter

Avoiding name collisions between classes from different libraries or teams
Organizing large codebases into logical, browsable units
Controlling visibility — package-private members are accessible only within the same package
Making it possible to distribute reusable code as a JAR that other projects can depend on

Tip

A common real-world layout mirrors the package structure under src/main/java (source) and src/test/java (tests), which is exactly what build tools like Maven and Gradle expect by default.