What is the difference between a package and a module in EK9?

← Getting Started · Ref: Q13

Modules and packages serve different purposes in EK9.

A MODULE is a namespace for organizing code:

  defines module com.example.utilities

Every .ek9 file declares exactly one module. Multiple files can share the same module name, and everything within the same module is automatically visible across those files. Modules control code organization, visibility, and the `references` mechanism for cross-module access.

A PACKAGE is optional metadata for distribution:

  defines package
    version as Version: 1.0.0-0
    description as String = "..."
    deps <- { ... }

A package block lives INSIDE a module and describes how to version, license, tag, and deploy that module as a distributable library. Only one file per module should contain a `defines package` block.

Key differences:
- Module: REQUIRED in every file. Organizes code into namespaces.
- Package: OPTIONAL. Only needed when you want to distribute your code as a library.

When you need a package:
- You are publishing a library for others to depend on
- You need version management (-IV, -SV, -PV)
- You want to declare dependencies on other libraries
- You want to deploy to a repository (-D)

When you do NOT need a package:
- You are writing an application (not a library)
- Your code has no external dependencies
- You are writing scripts or standalone programs

Think of it this way:
- Module = the code itself and its namespace
- Package = the shipping label on that code

Related questions for package specifics:
- How do I manage dependencies? (Q7)
- How do I tag my package for discovery? (Q8)
- How do I set a license? (Q9)
- How do I separate dev vs production dependencies? (Q10)
- How do I exclude transitive dependencies? (Q11)

The code example below shows a module that could work perfectly well without a package block. The package is only added when you decide to distribute it.

See Q6 for organizing modules. See Q2 for compile and run.

Example

defines module qa.getting.started.package.vs.module

  defines function
    greet() as pure
      -> name as String
      <- message as String: `Hello, ${name}!`

  defines program
    PackageVsModule()
      stdout <- Stdout()

      //This module works fine without a package block
      //Add defines package only when you need to distribute it
      stdout.println(greet("World"))
      stdout.println("This module has no package: it is a standalone program")
Other ways to ask this
  • When do I use defines module vs defines package?
  • Do I need both a module and a package?
  • Is a package the same as a module in EK9?
  • How do modules and packages relate to each other?

Coming from another language?

Java: package (namespace) vs Maven/Gradle project (distribution) are entirely separate. Python: module (namespace) vs PyPI package (distribution) are separate concepts with confusingly similar names. Rust: mod (namespace) vs crate/Cargo.toml (distribution). Go: package (namespace) vs module/go.mod (distribution). EK9 keeps both in the same source file but as distinct constructs.

Keywords: first, version, beginner, intro, module, start, organize, distribution, library, deploy, package, difference, defines, namespace