Module manifest (.psd1) in PowerShell - Deep Dive

Overview - Module manifest (.psd1)

What is it?

A module manifest (.psd1) is a special file in PowerShell that describes a module's metadata and settings. It tells PowerShell important details like the module's version, author, dependencies, and which files to load. Think of it as a profile card that helps PowerShell understand and manage the module properly. This file is written in a simple text format using PowerShell hashtables.

Why it matters

Without a module manifest, PowerShell would not know how to handle a module correctly, which can cause errors or unexpected behavior. The manifest helps ensure modules load the right files, check for required versions, and avoid conflicts. It also makes sharing and distributing modules easier and safer. Without manifests, managing many modules would be chaotic and error-prone.

Where it fits

Before learning about module manifests, you should understand basic PowerShell modules and how to create simple scripts. After mastering manifests, you can explore advanced module packaging, publishing to repositories, and module versioning strategies.

Mental Model

Core Idea

A module manifest is a detailed profile that tells PowerShell how to load, use, and manage a module safely and correctly.

Think of it like...

It's like a product label on a box that lists the contents, instructions, manufacturer, and warnings so the user knows exactly what to expect and how to use it.

┌─────────────────────────────┐
│       Module Manifest        │
├─────────────┬───────────────┤
│ Metadata    │ Version, Author│
│             │ Description   │
├─────────────┼───────────────┤
│ Settings    │ Required PSVer│
│             │ Required Mods │
├─────────────┼───────────────┤
│ Content     │ Scripts, DLLs │
│             │ Formats       │
└─────────────┴───────────────┘

Build-Up - 7 Steps

1

Foundation

What is a Module Manifest

Concept: Introduces the basic idea of a module manifest and its role in PowerShell modules.

A module manifest is a .psd1 file that contains metadata about a PowerShell module. It is a text file formatted as a PowerShell hashtable. This file tells PowerShell important information like the module's version, author, and which scripts or binaries to load. It helps PowerShell manage the module properly.

Result

You understand that a manifest is a special file that describes a module's details and controls how it loads.

Knowing that a manifest is a descriptive file helps you see modules as packages with instructions, not just code files.

2

Foundation

Basic Structure of a .psd1 File

Concept: Shows the simple syntax and key parts of a module manifest file.

A manifest file is a PowerShell hashtable with keys and values. Common keys include ModuleVersion, Author, Description, and RootModule. For example: @{ ModuleVersion = '1.0.0' Author = 'Jane Doe' RootModule = 'MyModule.psm1' } This structure is easy to read and edit with any text editor.

Result

You can recognize and write a simple manifest file with basic metadata.

Understanding the manifest as a hashtable connects it to PowerShell's core data structures, making it easier to customize.

3

Intermediate

Specifying Module Content and Dependencies

🤔Before reading on: do you think a manifest can list only scripts, or can it also include binaries and other files? Commit to your answer.

Concept: Explains how to declare which files the module uses and what other modules or PowerShell versions it needs.

In the manifest, you can specify RootModule or NestedModules to list scripts or DLLs the module loads. You can also set RequiredModules to declare dependencies on other modules, and RequiredPSVersion to ensure the PowerShell version is compatible. This helps PowerShell load everything needed and avoid errors.

Result

The manifest controls what files load and checks for required modules and PowerShell versions before loading.

Knowing how to declare dependencies and content prevents runtime errors and makes modules more reliable and maintainable.

4

Intermediate

Controlling Exported Commands and Functions

🤔Before reading on: do you think all functions in a module are available by default, or must they be explicitly exported? Commit to your answer.

Concept: Shows how the manifest controls which commands and functions are visible to users of the module.

The manifest has keys like FunctionsToExport and CmdletsToExport. You list the names of functions or cmdlets you want users to access. If you set these to '*', all are exported. Otherwise, only listed items are visible. This controls the module's public interface and hides internal details.

Result

You can control the module's public commands, making it easier to maintain and safer to use.

Understanding export control helps you design clean modules with clear interfaces and avoid exposing internal helpers.

5

Intermediate

Using the New-ModuleManifest Cmdlet

Concept: Introduces the PowerShell command that creates a manifest template automatically.

PowerShell provides New-ModuleManifest to generate a basic .psd1 file. You run: New-ModuleManifest -Path 'MyModule.psd1' -RootModule 'MyModule.psm1' -Author 'Jane Doe' -ModuleVersion '1.0.0' This creates a manifest with default keys you can edit. It saves time and ensures correct syntax.

Result

You can quickly create a manifest file with proper structure and start customizing it.

Using built-in tools reduces errors and speeds up module development.

6

Advanced

Advanced Manifest Settings and Security

🤔Before reading on: do you think manifests can control script signing or module visibility? Commit to your answer.

Concept: Explores less obvious manifest keys that affect security and module behavior.

Manifests can include PrivateData for custom info, ScriptsToProcess to run scripts on module import, and RequiredAssemblies for .NET dependencies. You can also specify PowerShellVersion compatibility and set CompatiblePSEditions (like Desktop or Core). These settings help secure and tailor module loading.

Result

You can fine-tune module behavior and compatibility, improving security and user experience.

Knowing advanced keys lets you build professional modules that behave well across environments and protect users.

7

Expert

Manifest Internals and Module Loading Process

🤔Before reading on: do you think PowerShell reads the manifest before or after loading the module files? Commit to your answer.

Concept: Details how PowerShell uses the manifest internally during module import and loading.

When you import a module, PowerShell first reads the manifest file to check metadata, dependencies, and version requirements. It uses this info to decide which files to load and what commands to export. The manifest acts as a gatekeeper, preventing incompatible or incomplete modules from loading. This process improves reliability and security.

Result

You understand the critical role of the manifest in controlling module loading and preventing errors.

Understanding the loading sequence helps debug module issues and design manifests that avoid common pitfalls.

Under the Hood

PowerShell parses the .psd1 file as a PowerShell hashtable at runtime when a module is imported. It reads keys like RootModule, RequiredModules, and FunctionsToExport to control loading order, dependency checks, and command visibility. This parsing happens before any module code runs, allowing PowerShell to enforce version compatibility and dependency presence. The manifest also supports custom data via PrivateData, which PowerShell ignores but tools can use.

Why designed this way?

The manifest was designed as a simple, human-readable PowerShell data file to leverage existing syntax and avoid inventing a new format. This choice makes it easy to edit and script. It centralizes module metadata to improve module management, versioning, and dependency handling. Alternatives like XML or JSON were rejected to keep it native to PowerShell and reduce complexity.

┌───────────────┐
│ Import-Module │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Read .psd1    │
│ (Parse Hashtable)│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Check Versions│
│ Check Dependencies│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Load Scripts  │
│ Export Commands│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does a module manifest automatically include all scripts in the module folder? Commit to yes or no.

Common Belief: Many think the manifest automatically includes every script in the module folder without listing them.

Reality: The manifest only loads files explicitly listed in RootModule or NestedModules. Other scripts are ignored unless imported manually.

Why it matters: Assuming all scripts load can cause missing functions or commands, leading to runtime errors and confusion.

Quick: Is the manifest required for all PowerShell modules? Commit to yes or no.

Common Belief: Some believe every module must have a manifest file to work.

Reality: Manifests are optional. Simple modules can work with just a .psm1 script file, but manifests add control and metadata.

Why it matters: Thinking manifests are mandatory can discourage beginners from creating simple modules and slow learning.

Quick: Does setting FunctionsToExport to '*' export all functions including private helpers? Commit to yes or no.

Common Belief: People often believe '*' exports only public functions, excluding private ones.

Reality: '*' exports all functions defined in the module, including those intended as private unless explicitly hidden.

Why it matters: This can unintentionally expose internal functions, causing namespace pollution or security risks.

Quick: Does the manifest control the order in which nested modules load? Commit to yes or no.

Common Belief: Some think nested modules load in the order they are listed in the manifest.

Reality: PowerShell does not guarantee load order of nested modules; it may vary, so dependencies should not rely on order.

Why it matters: Assuming load order can cause subtle bugs when nested modules depend on each other.

Expert Zone

1

The PrivateData section can store custom metadata used by tools like PowerShell Gallery or build systems without affecting module loading.

2

ScriptsToProcess runs scripts every time the module imports, which can be used for initialization but may cause side effects if not carefully managed.

3

CompatiblePSEditions lets you specify if a module works only on Desktop PowerShell, PowerShell Core, or both, helping avoid runtime errors on unsupported platforms.

When NOT to use

Module manifests are less useful for very simple scripts or one-off functions where overhead is unnecessary. In such cases, a plain .psm1 file suffices. Also, for dynamic modules generated at runtime, manifests cannot describe changing content. Alternatives include script modules without manifests or binary modules with embedded metadata.

Production Patterns

In production, manifests are used to enforce strict versioning and dependency rules, control exported commands to create clean APIs, and specify compatible PowerShell editions. They are also used to embed help files, define required assemblies, and automate module signing policies. Large projects often automate manifest generation and validation as part of CI/CD pipelines.

Connections

Package.json (Node.js)

Both are metadata files that describe a package/module, its dependencies, and versioning.

Understanding module manifests in PowerShell helps grasp how other ecosystems manage package metadata and dependencies, showing a common pattern in software packaging.

Software Product Labels

Module manifests function like product labels that provide essential information and usage instructions.

Recognizing manifests as labels clarifies their role in communication between the module creator and user, ensuring safe and correct usage.

Library Cataloging in Libraries

Just as libraries catalog books with metadata for easy retrieval and management, manifests catalog modules for PowerShell.

This connection shows how organizing information with metadata is a universal concept across fields, improving discoverability and management.

Common Pitfalls

#1 Assuming all functions in the module are automatically exported.

Wrong approach:

@{
FunctionsToExport = @()
}
# No functions exported, module appears empty.

Correct approach:

@{
FunctionsToExport = '*'
}
# Exports all functions, making them available to users.

Root cause:

Misunderstanding that FunctionsToExport controls visibility; empty array means no exports.

#2 Forgetting to update ModuleVersion after changes.

Wrong approach:

@{
ModuleVersion = '1.0.0'
# Module updated but version unchanged
}

Correct approach:

@{
ModuleVersion = '1.1.0'
# Version updated to reflect changes
}

Root cause:

Not realizing versioning is critical for dependency management and update tracking.

#3 Listing scripts in the module folder but not in RootModule or NestedModules.

Wrong approach:

# Module folder contains Helper.ps1 but manifest lacks reference
@{
RootModule = 'MainModule.psm1'
}

Correct approach:

@{
RootModule = 'MainModule.psm1'
NestedModules = @('Helper.ps1')
}

Root cause:

Assuming PowerShell loads all files in the folder automatically.

Key Takeaways

A module manifest (.psd1) is a PowerShell file that describes a module's metadata, dependencies, and content to control how it loads and behaves.

Manifests use a simple PowerShell hashtable format, making them easy to read and edit with familiar syntax.

They help ensure modules load the right files, export only intended commands, and check for required PowerShell versions and dependencies.

Using manifests improves module reliability, security, and maintainability, especially in complex or shared environments.

Understanding the manifest's role in the module loading process is key to debugging and designing professional PowerShell modules.