Back to series
· 12 min read

Modules & Packages


I. What Is a Module?

A module is a unit of code organization provided by a programming language or runtime environment. It groups related variables, functions, types, and other definitions together and exposes functionality to the outside through a well-defined interface.

For example, a user management system might contain:

  • User registration.
  • User login.
  • User information queries.
  • User information modification.
  • User permission management.

If all code is placed in a single file, it becomes increasingly difficult to maintain as the business grows.

It can be split into multiple modules by function:

user/
├── register
├── login
├── profile
└── permission

Each module is responsible for a relatively independent function and collaborates with other modules through interfaces.

1.1 Core Roles of Modules

Modules mainly address the following problems:

1. Code Organization

Manage related code centrally and prevent all functionality from being mixed together.

2. Naming Isolation

Different modules can have variables, functions, or types with the same name, reducing naming conflicts.

3. Implementation Encapsulation

A module can expose only the necessary interfaces and hide internal implementation details.

4. Code Reuse

A module can be imported and called by multiple programs or other modules.

5. Dependency Management

Clarify the reference relationships between modules, making it easier to maintain the program structure.

6. Independent Development

Different developers can develop and test in parallel around module boundaries.

1.2 Basic Composition of a Module

A typical module may contain the following:

Component Description
Module name A unique name or path that identifies the module
Variables Data definitions inside the module
Functions Functionality provided by the module
Types Classes, structs, interfaces, enums, etc.
Constants Fixed values defined inside the module or exposed externally
Exported interfaces Members that external code is allowed to access
Internal implementation Implementation details not exposed externally
Dependency declarations Other modules that the module needs to use

The structure of a module is not determined entirely by the number of files.

In different languages, a module may correspond to a source file, a folder, a compilation unit, or a code object dynamically created by the runtime.

II. What Is a Package?

A package is usually a higher-level structure used to organize multiple modules, manage namespaces, and provide code distribution capabilities.

For example, a network communication library might contain:

network/
├── http
├── websocket
├── tcp
├── udp
└── dns

Here, network can serve as a package containing multiple functional modules.

Packages are typically used to:

  • Organize related modules.
  • Establish namespace hierarchies.
  • Manage public interfaces.
  • Distribute reusable code.
  • Declare external dependencies.
  • Manage versions.
  • Form independent software components.

2.1 Relationship Between Modules and Packages

In many languages, a module can be understood as the basic unit of code organization, and a package as a container that organizes multiple modules.

flowchart TD
    A["Application"] --> B["Business Package"]
    A --> C["Infrastructure Package"]
    B --> D["User Module"]
    B --> E["Order Module"]
    B --> F["Payment Module"]
    C --> G["Database Module"]
    C --> H["Cache Module"]
    C --> I["Logging Module"]

    style A fill:#FFF5DE,stroke:#E8D29A,color:#334155
    style B fill:#E5F4EC,stroke:#A3CBB5,color:#334155
    style C fill:#E5F4EC,stroke:#A3CBB5,color:#334155
    style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style G fill:#F3EDFC,stroke:#C4B2E3,color:#334155
    style H fill:#F3EDFC,stroke:#C4B2E3,color:#334155
    style I fill:#F3EDFC,stroke:#C4B2E3,color:#334155
    linkStyle default stroke:#A3B8AC,stroke-width:1.5px

However, it must be noted: there is no unified hierarchical relationship between modules and packages that applies to all programming languages.

Definitions vary greatly across languages:

  • Python: A module usually corresponds to a .py file, and a package is usually used to organize multiple modules.
  • Java: Packages are mainly used for namespaces and type organization, and the compilation unit is usually a source file.
  • Go: A package is an important unit of source code organization, compilation, and access control; a package usually consists of multiple source files in the same directory.
  • Rust: Modules are used to organize code hierarchy, a Crate is the compilation unit, and a Cargo Package is the unit of project and distribution management.
  • JavaScript: An ES Module usually uses a file as a module, and an npm Package is the unit of publishing and dependency management.
  • C/C++: Code is usually organized using header files, source files, namespaces, libraries, and build systems; there is no fully corresponding general system of modules and packages.

Therefore, when learning a specific language, it is necessary to distinguish between modules, packages, namespaces, compilation units, and software distribution units.

III. Core Concepts of Modules and Packages

3.1 Namespace

A namespace is used to organize names and avoid conflicts between identifiers in different code regions.

For example:

# user.py
name = "User Module"

def get_name():
    return name
# order.py
name = "Order Module"

def get_name():
    return name

Both modules define name and get_name, but they are in different module namespaces.

When calling:

import user
import order

print(user.get_name())
print(order.get_name())

Output:

User Module
Order Module

The module name is equivalent to the namespace prefix used when accessing members.

Namespaces can adopt a hierarchical structure:

company
├── user
│   ├── account
│   └── permission
└── order
    ├── payment
    └── delivery

For example:

company.user.account
company.order.payment

This structure can reduce the risk of name conflicts in large projects.

Note that a namespace does not necessarily imply a separate runtime memory space. It is first and foremost a mechanism for organizing and resolving names.

3.2 Import

Importing is the mechanism that brings definitions provided by other modules into the current code environment.

For example, in Python:

import math

result = math.sqrt(16)

print(result)

Here, the math module is brought in via import, and then its members are accessed.

Common import styles:

# Import the entire module
import math

# Use an alias
import math as m

# Import specific members
from math import sqrt

# Import multiple members
from math import sqrt, pow

Different languages use different import syntax:

Language Import Mechanism
Python import, from...import
Java import
JavaScript import
TypeScript import
Go import
Rust use, mod
C #include
C++ #include, import (module mechanism)

Note that #include in C/C++ is a preprocessing directive and is not exactly the same as the runtime or language-level module import mechanisms of languages such as Python and JavaScript.

3.3 Export

Exporting is the mechanism by which a module exposes variables, functions, types, or other members to the outside.

For example, JavaScript:

// math.js
export function add(a, b) {
    return a + b;
}

export const PI = 3.14159;

Other modules can import them:

// main.js
import { add, PI } from "./math.js";

console.log(add(10, 20));
console.log(PI);

Exports can be divided into:

  • Named exports (Named Export).
  • Default exports (Default Export).
  • Public types or interfaces.
  • Public functions and constants.

Export mechanisms differ across languages.

For example:

  • Java controls the accessibility of classes and members through access modifiers.
  • Go controls cross-package visibility through the capitalization of the first letter of identifiers.
  • Rust uses pub to control public visibility.
  • Python generally manages member access through naming conventions and module attributes, and has no enforced universal private member access control mechanism.
  • C/C++ generally manages interfaces through header files, linking, and language access control mechanisms.

3.4 Access Control

Modules and packages are not only used to organize code; they also need to control which members can be accessed externally.

Common access levels:

Access level Typical meaning
Public Exposed externally
Private Accessible only within a specific type or scope
Protected Allows access through specific inheritance relationships
Internal Accessible within a specified assembly or module scope
Package-private Accessible within package scope

Different languages do not define these levels in exactly the same way.

For example, Java:

package com.example.user;

public class User {
    public String name;

    private String password;

    protected int age;

    void internalMethod() {
        // Default package-level access
    }
}

Here:

  • public: can be accessed by other packages.
  • private: can only be accessed within the current class.
  • protected: allows access within the same package, and also allows access by subclasses that meet inheritance rules.
  • No access modifier: has package-level access.

Access control helps hide internal implementation and reduce external code's dependence on module internals.

IV. Modular Design (Modularization)

Modularization is the process of splitting a complex system into multiple relatively independent modules with clear responsibilities.

Modularization is not just splitting code into multiple files; it is about establishing reasonable functional boundaries and dependency relationships.

4.1 Why Is Modularization Needed?

Suppose a system includes businesses such as users, orders, payments, and inventory.

If all logic is written in a single file:

application.py

The following problems may arise:

  • The code file becomes too large.
  • Different business logic is mixed together.
  • Modifying one feature affects other features.
  • Code is difficult to reuse.
  • The testing scope is difficult to control.
  • Conflicts easily occur during multi-person collaboration.

After modularization:

application/
├── user/
│   ├── service.py
│   └── repository.py
├── order/
│   ├── service.py
│   └── repository.py
├── payment/
│   ├── service.py
│   └── gateway.py
└── inventory/
    ├── service.py
    └── repository.py

Each module organizes code around relatively clear business responsibilities.

4.2 High Cohesion and Low Coupling

Important goals of modular design are high cohesion and low coupling.

High cohesion: The functions within a module are organized around the same clear responsibility, and members have a strong business relationship with one another.

Low coupling: Minimize unnecessary dependencies between modules to reduce the impact of changes in one module on other modules.

For example:

The user module is responsible for user information management, the order module for order business, and the payment module for payment processing.

flowchart TD
    A["Application Entry"] --> B["Order Module"]
    B --> C["User Module"]
    B --> D["Payment Module"]
    B --> E["Inventory Module"]
    D --> F["Payment Interface"]
    E --> G["Inventory Interface"]

    style A fill:#FFF5DE,stroke:#E8D29A,color:#334155
    style B fill:#E5F4EC,stroke:#A3CBB5,color:#334155
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#F3EDFC,stroke:#C4B2E3,color:#334155
    style G fill:#F3EDFC,stroke:#C4B2E3,color:#334155
    linkStyle default stroke:#A3B8AC,stroke-width:1.5px

The key here is not the number of modules, but whether the module boundaries are reasonable.

If modules are split too little, it is easy to end up with large modules with confused responsibilities; if split too much, the cost of inter-module communication and dependency management may increase.

4.3 Module Boundaries and Interface Design

Modules usually collaborate through interfaces.

For example, the order module should not depend directly on all the internal implementations of the payment module; instead, it should depend on the stable interface provided by the payment module.

This can be abstracted as:

Order Module
    |
    | Call payment interface
    |
Payment Interface
    |
    | Concrete implementation
    |
Payment Service

Interface design needs to focus on:

  • Input parameters.
  • Return results.
  • Error handling.
  • Data structures.
  • Permission boundaries.
  • Compatibility.
  • Version changes.

A good module interface should be as stable as possible, while the internal implementation can evolve independently.

V. Module Dependencies and Dependency Relationships

Modules are usually not completely independent; they form dependencies through imports, calls, and interfaces.

5.1 What Is a Module Dependency?

A module dependency means that a module needs to use the capabilities provided by another module when compiling, running, or executing a certain function.

For example:

# order.py
from payment import process_payment

def create_order():
    process_payment()

Here the order module depends on the payment module.

Dependencies can form a directed graph:

flowchart TD
    A["Application Entry"] --> B["Order Module"]
    B --> C["User Module"]
    B --> D["Payment Module"]
    D --> E["Payment Gateway"]
    B --> F["Inventory Module"]

    style A fill:#FFF5DE,stroke:#E8D29A,color:#334155
    style B fill:#E5F4EC,stroke:#A3CBB5,color:#334155
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style E fill:#F3EDFC,stroke:#C4B2E3,color:#334155
    style F fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    linkStyle default stroke:#A3B8AC,stroke-width:1.5px

5.2 Direct and Transitive Dependencies

Direct Dependency

Module A directly references module B.

For example:

A → B

Transitive Dependency

Module A depends on B, and B in turn depends on C, so in some cases A indirectly depends on C.

A → B → C

Transitive dependencies are very common in large projects.

They can cause the following problems:

  • Dependency version conflicts.
  • Unnecessary dependency propagation.
  • Propagation of security vulnerabilities.
  • Increased build size.
  • Compatibility issues during upgrades.

Therefore, dependency management must focus not only on the modules you directly introduce, but also on the complete dependency tree.

5.3 Circular Dependency

A circular dependency means that multiple modules form a closed loop of dependencies.

For example:

A → B
B → C
C → A

This structure increases the complexity of module initialization, compilation, and maintenance.

flowchart TD
    A["Module A"] --> B["Module B"]
    B --> C["Module C"]
    C --> A

    style A fill:#F3EDFC,stroke:#C4B2E3,color:#334155
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#E5F4EC,stroke:#A3CBB5,color:#334155
    linkStyle default stroke:#A3B8AC,stroke-width:1.5px

Circular dependencies can lead to:

  • An uncertain order of module initialization.
  • Some modules being accessed before they have finished initializing.
  • Compile-time dependencies that are difficult to resolve.
  • Difficulty in testing and refactoring.
  • Blurred boundaries of module responsibilities.

Different languages handle circular dependencies in different ways:

Language Typical behavior
Python May encounter issues where partially initialized modules are accessed
JavaScript ES Modules support circular references, but may encounter issues such as the temporal dead zone
Java Classes can reference each other, but initialization and design still require care
Go Circular imports cannot be formed within the same package
Rust Module paths can reference each other, but type definitions and dependency relationships are still constrained by compilation rules
C/C++ Mutual inclusion of header files may cause declaration dependency and compilation issues

5.4 How to Resolve Circular Dependencies?

Common solutions:

1. Extract Common Modules

Extract functionality that multiple modules depend on into an independent module.

A → Common
B → Common
C → Common

2. Introduce Interfaces or Abstraction Layers

Modules depend on interfaces rather than directly on concrete implementations.

3. Adjust Responsibility Boundaries

Re-analyze module responsibilities to avoid two modules taking on each other's business logic.

4. Use Dependency Injection

External containers or callers provide dependency objects, reducing direct creation and references between modules.

5. Decouple via Events or Messages

Use event notifications or messaging mechanisms to avoid direct call relationships between modules.

6. Package Management

Package management refers to the mechanism for managing the acquisition, installation, upgrade, uninstallation, version constraints, and dependency resolution of software packages.

Modern software development usually uses a large number of third-party libraries and rarely relies entirely on the standard library to implement all functionality.

For example:

  • Python uses the PyPI ecosystem and pip.
  • JavaScript uses npm, pnpm, and Yarn.
  • Java uses Maven and Gradle.
  • Go uses Go Modules.
  • Rust uses Cargo.
  • PHP uses Composer.
  • .NET uses NuGet.

6.1 What Is a Software Package?

A software package is usually a software unit that can be distributed, installed, and reused.

It may contain:

  • Source code.
  • Compiled binary files.
  • Modules or libraries.
  • Metadata.
  • Version information.
  • Dependency declarations.
  • Configuration files.
  • Documentation.

A software package is not necessarily equivalent to a module in a programming language.

For example, an npm package can contain multiple JavaScript modules; a Python distribution can also contain multiple Python packages and modules.

Therefore, it is necessary to distinguish between:

  • Source code modules.
  • Language packages.
  • Software distribution packages.
  • Dependency management units.

6.2 Package Manager

A package manager is a tool used to automate software package management.

Typical responsibilities include:

  1. Locate software packages.
  2. Download software packages.
  3. Install software packages.
  4. Resolve dependencies.
  5. Check version compatibility.
  6. Upgrade and uninstall software packages.
  7. Manage the local dependency environment.
  8. Verify package integrity.

Typical workflow:

flowchart TD
    A["Declare project dependencies"] --> B["Package manager reads configuration"]
    B --> C["Resolve dependencies"]
    C --> D["Check version constraints"]
    D --> E["Download packages"]
    E --> F["Install dependencies"]
    F --> G["Generate or update lockfile"]
    G --> H["Build or run project"]

    style A fill:#E5F4EC,stroke:#A3CBB5,color:#334155
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#F3EDFC,stroke:#C4B2E3,color:#334155
    style D fill:#FFF5DE,stroke:#E8D29A,color:#334155
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#E5F4EC,stroke:#A3CBB5,color:#334155
    style G fill:#F3EDFC,stroke:#C4B2E3,color:#334155
    style H fill:#E8EDF2,stroke:#B8C3CE,color:#334155
    linkStyle default stroke:#A3B8AC,stroke-width:1.5px

6.3 Package Registry

A package registry is a service used to store and distribute software packages.

Common public registries:

Ecosystem Primary Registry
Python PyPI
JavaScript npm Registry
Java Maven Central
Go Go Module Proxy
Rust crates.io
PHP Packagist
.NET NuGet Gallery

Package managers typically fetch packages through a registry and install them into the local environment or the project's dependency directory.

Note that public registries are not the only source for all dependencies. Enterprise projects may also use private registries, mirror registries, or internal artifact repositories.

VII. Dependency Versioning

Packages usually carry version numbers, and a project uses version constraints to determine which versions may be used.

7.1 Semantic Versioning

Semantic Versioning (SemVer) is a common version numbering specification.

Typical format:

MAJOR.MINOR.PATCH

For example:

2.5.3

Meaning of each part:

Version Part Meaning Common Changes
MAJOR Major version number Incompatible API changes
MINOR Minor version number New backward-compatible features
PATCH Patch version number Backward-compatible bug fixes

For example:

  • 2.5.3: the current version.
  • 2.6.0: adds new backward-compatible features.
  • 2.5.4: fixes a bug.
  • 3.0.0: may contain incompatible API changes.

Semantic Versioning is a convention, and it does not mean every package follows it strictly.

7.2 Version Constraints

Projects usually do not declare only a single fixed version; instead, they use version constraints to express the allowed version range.

For example:

{
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "~4.17.0"
  }
}

Under the common npm semantic versioning rules:

  • ^4.18.0: allows compatible 4.x versions, but does not move to 5.0.0.
  • ~4.17.0: allows patch versions of 4.17.x, but does not move to 4.18.0.

Note that different package managers and version constraint syntaxes are not entirely the same, and npm's rules cannot be applied directly to every ecosystem.

7.3 Lockfile

A lockfile records the exact resolved versions of dependencies and related information.

Common files:

Ecosystem Lockfile
npm package-lock.json
pnpm pnpm-lock.yaml
Yarn yarn.lock
Python Depends on the tool, for example Poetry's poetry.lock
Rust Cargo.lock
Go go.sum records module content checksums, while go.mod declares module dependencies
PHP composer.lock
.NET packages.lock.json (when the lockfile mechanism is enabled)

The main value of a lockfile:

  • Pins the dependency resolution result.
  • Improves consistency across team development environments.
  • Reduces the uncertainty introduced by dependency upgrades.
  • Improves the reproducibility of the build process.

It is important to distinguish dependency declaration files from lockfiles; their responsibilities are not entirely the same.

For example, Go's go.mod is used to declare the module path and dependency versions, while go.sum is used to record checksums of module content; it is not a complete dependency lockfile in the simple sense.

VIII. Dependency Resolution and Dependency Conflicts

When a project depends on multiple packages, the package manager needs to compute a set of dependencies that satisfies the version constraints.

8.1 Dependency Tree

For example:

Application
├── Package A
│   └── Package C
└── Package B
    └── Package C

The application directly depends on A and B, and both A and B depend on C.

In this case, C is a transitive dependency of the application.

The dependency tree may further expand into a complex dependency graph.

8.2 Version Conflicts

Suppose:

Package A → Library C 1.x
Package B → Library C 2.x