Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

How to Import Classes in Java: Syntax and Common Pitfalls

Learn how to use the Java import statement to reference classes from other packages, handle naming conflicts, and avoid common compile errors.

~5 min readJava
#Java#import statement#packages#static import
A Java class being imported from a package, visualized as a file moving into a project structure.

The Java import declaration is one of the first things you encounter when moving beyond a single-file Java program. It tells the compiler which fully qualified class names you want to refer to by their simple names. Without it, you would have to write java.util.List every time you used a list, which quickly becomes unreadable. This article explains the syntax, the behavior of different import forms, and the pitfalls that cause confusing compile errors.

The Role of the import Statement

An import declaration does not physically include code or affect runtime performance. It is a compile-time convenience that maps simple names to fully qualified names. When you write import java.util.ArrayList;, the compiler resolves every occurrence of ArrayList in that source file to java.util.ArrayList. The compiled bytecode still references the fully qualified class, so imports have zero runtime cost.

Standard Java build tools and IDEs expect source files to reside in a directory structure that matches their package declaration. If you declare package com.example.util;, the file is conventionally placed in com/example/util/. The import statement then lets you reference classes from other packages without repeating the package prefix.

Importing a Single Class

The most common form is a single-type import:

java
import java.util.ArrayList; import java.util.List; public class Example { public static void main(String[] args) { List<String> items = new ArrayList<>(); items.add("one"); System.out.println(items.size()); } }

This is explicit and self-documenting. A reader can see exactly which classes are used. It also avoids ambiguity when two packages contain a class with the same name. For example, java.util.Date and java.sql.Date both exist. Importing both with single-type imports causes a compile error because the simple name Date becomes ambiguous. The compiler reports a conflict, and you must either use fully qualified names for one of them or import only one.

Wildcard Imports and Their Tradeoffs

A wildcard import brings in all public classes and interfaces from a package:

java
import java.util.*;

This is convenient when you use many types from the same package. However, it has two practical downsides. First, it can introduce ambiguity. If you also import java.sql.*, the simple name Date is still ambiguous. The compiler does not know which one you mean. Second, wildcard imports obscure the origin of a class. A developer reading the file cannot tell whether List came from java.util or another imported package without checking the entire package list.

The Java Language Specification allows wildcard imports, but they do not cause a performance penalty because resolution happens at compile time. The real cost is maintainability. Many style guides discourage wildcard imports; Google's Java Style Guide, for example, prohibits them entirely. For a professional codebase, prefer explicit imports.

Static Imports for Members

Static imports allow you to refer to static members of a class without qualifying them with the class name. This is different from importing a class itself. For example:

java
import static java.lang.Math.PI; public class Circle { public static double area(double radius) { return PI * radius * radius; } }

Static imports are useful for constants and utility methods, but overuse can make code harder to read because the origin of a static member is no longer obvious. A wildcard static import like import static java.lang.Math.*; brings in all static members, which can pollute the namespace and cause conflicts with your own methods. Use static imports sparingly, typically for a small set of constants or a few well-known utility methods.

Handling Naming Conflicts

When two imported classes share the same simple name, the compiler rejects the code. The solution is to use a fully qualified name for at least one of them:

java
import java.util.Date; // import java.sql.Date; // causes conflict public class Conflict { public static void main(String[] args) { Date utilDate = new Date(); java.sql.Date sqlDate = new java.sql.Date(utilDate.getTime()); } }

This pattern is common when working with both legacy java.util.Date and java.sql.Date in JDBC code. The fully qualified name is verbose but removes ambiguity. Another option is to avoid importing either and use fully qualified names throughout, but that is rarely worth the extra typing.

Import and Package Structure

The import statement only works for classes that are accessible. A top-level class must be declared public to be imported from another package. Package-private classes (no modifier) are only visible within their own package, so an import of a package-private class fails with a compile error. Also, importing a class does not automatically import its nested types. You can import a public nested type directly with a single-type import, such as import com.example.Outer.Inner;, or you can import the outer class and refer to the nested type as Outer.Inner. If it is an inner (non-static) class, you still need an instance of the outer class to create it.

When you create your own packages, keep the package hierarchy meaningful. Imports then reflect the logical structure of your code. A common mistake is to place many unrelated classes in a single package and rely on wildcard imports. That reduces the benefit of packages as a namespace mechanism.

Common Mistakes and Compile Errors

One frequent error is writing import after a class declaration. Imports must appear at the top of the file, after the package declaration (if any) and before the class definition. Another is misspelling the package or class name; the compiler reports cannot find symbol. A more subtle issue is importing a class that is not public. For example, if you try to import a package-private class from another package, you get a compile error even though the class exists.

Another mistake is assuming that importing a class also imports its nested classes. Nested types are not automatically imported. To use a public nested type, import it directly with a single-type import (import com.example.Outer.Inner;) or import the outer class and refer to it as Outer.Inner.

When Imports Affect Maintainability

Imports are a form of dependency documentation. A file with dozens of explicit imports tells you exactly what external types the code depends on. A file with a wildcard import hides that information. When you refactor or upgrade libraries, explicit imports make it easier to identify which classes are affected. For example, if you remove a dependency on a package, the compiler will flag missing imports, but a wildcard import will not fail until you actually use a class that no longer exists.

In large codebases, some teams use tools like Checkstyle or PMD to enforce explicit import rules. These tools can flag wildcard imports and suggest explicit ones. The choice is a style decision, but consistency matters more than the specific rule. If your team standardizes on explicit imports, the codebase becomes easier to navigate and review.

A final consideration is the java.lang package. Classes in java.lang such as String, Integer, and System are automatically imported in every source file. You do not need an explicit import java.lang.String;. This is part of the Java Language Specification and reduces boilerplate for the most common types.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.