skip to content

In Kotlin, must a file's package declaration mirror its directory structure on disk? Explain what the compiler actually requires.

level: juniorimportance: must knowfreq 55%

answer

  1. Java enforces dir = package; Kotlin does not
  2. package = first non-comment line
  3. No package line => default/root package
  4. Convention still recommends mirroring
  5. FQN comes from package keyword, not folder

basics

~20 s

No. In Kotlin the package name does not have to match the folder path. The compiler accepts any package name regardless of where the file lives, though matching folders to packages is still recommended for clarity.

solid answer

~40 s

Unlike Java, Kotlin does not force the package declaration to mirror the directory tree. You can put a file in src/foo/ and declare `package com.acme.bar` and it compiles fine. The `package` statement (first non-comment line) defines the fully qualified name used for resolution and JVM output. Files with no `package` line belong to the default (root) package. Despite the freedom, the Kotlin style guide recommends mirroring directories to packages, omitting a common root prefix, so navigation and tooling stay predictable. Build tools like Gradle/Maven still use the source root, and IDEs warn when package and directory diverge, but it is a convention, not a hard rule. The flexibility helps with top-level functions and small files but should not be abused.

code

kotlin · 5 lines
kotlin
// File can sit in any folder; this line decides the FQN.
package com.acme.util

fun greet(name: String) = "Hi $name"
// FQN: com.acme.util.greet

go deeper

for a junior

Knows the package declaration is optional in placement and Kotlin doesn't enforce folder matching.

for a middle

Explains FQN derives from the package keyword and that convention still favors mirroring.

for a senior

Discusses tooling implications, default package pitfalls, and Java interop expectations.

for a principal

Frames team-level conventions, monorepo source-root strategy, and migration risks when packages drift from directories.

## What a package is A **package** is a namespace that groups related declarations (classes, functions, properties) and forms part of their **fully qualified name (FQN)**. You declare it with the `package` keyword as the first non-comment statement in a file: ```kotlin package com.acme.billing fun computeTax(amount: Double) = amount * 0.2 ``` Here `computeTax`'s FQN is `com.acme.billing.computeTax`. ## Java vs Kotlin In **Java**, the package declaration is required to match the directory: a class in package `com.acme.billing` must live in `com/acme/billing/`. The Java compiler enforces this. In **Kotlin**, this is **not enforced**. A file can declare any package independent of its physical folder. A file with no `package` line belongs to the **default (root) package**. ## Why the freedom exists Kotlin allows **multiple top-level declarations per file** and files named freely (not tied to a class name). Decoupling package from directory follows naturally. It is convenient for small utility files holding several top-level functions. ## The convention still recommended The official Kotlin **coding conventions** say: place source in directories matching packages, but you may **omit a common root prefix** (e.g., skip `com.acme` directories). IDEs like IntelliJ show a warning when the declared package and directory disagree, and offer a quick-fix. ## Practical impact - Compilation succeeds regardless of folder. - The FQN (used for imports and reflection) comes from the `package` line, not the path. - Mismatches hurt readability and navigation, so teams usually keep them aligned.

  • What happens if you omit the package declaration entirely?
    The file's declarations land in the default (root) package, and their FQN is just the simple name. This is discouraged for library/production code.
  • Will the IDE complain about a mismatch?
    IntelliJ shows a warning/inspection and offers to move the file or change the package, but the compiler still builds it.

A package is like a mailing address written on the envelope; Kotlin doesn't check whether you actually live in that street.

saying these in an interview costs you the question

  • Claiming Kotlin enforces directory-package matching like Java
  • Saying a mismatch fails compilation
  • Confusing 'package' with the file name
  • Thinking no package means a compile error
  • Asserting the folder determines the FQN

context

resolving links…