How to Create a PowerShell Module: A Beginner’s Guide

PowerShell modules are essential for scriptwriters and system administrators to organize and reuse their code. A module is a package of related functions, cmdlets, and resources bundled together for easy sharing and deployment. Creating a custom PowerShell module allows you to centralize functionality, streamline code reuse, and distribute your work to others. This guide walks you through the steps to create a PowerShell module, covering the required files and how to include pertinent metadata in the module manifest.

Step 1: Understanding the Core Files

Creating a custom PowerShell module requires a few key components:

Module Script File

The .psm1 file is the heart of your module. It is a script file that defines the functionality of a PowerShell module. It contains the core code for the module, including the functions, cmdlets, aliases, and variables that the module provides. PowerShell executes the .psm1 file when importing a module, making the module’s functionality available in the current PowerShell terminal.

Module Manifest File

The manifest file provides metadata about your module, including the author, version, description, and licensing information. This file is required to create a complete and properly functioning PowerShell module. The .psm1 file works in tandem with the .psd1 manifest file. While the .psd1 file provides metadata and controls module exports, the .psm1 file contains the actual functionality.

Step 2: Setting Up the Directory Structure

The module must follow a specific directory structure to be loaded correctly by PowerShell. The root folder name should match the module’s name. Place your .psm1 and .psd1 files in this folder to ensure PowerShell loads the files correctly.

Here is an example directory structure for MyModule with the required.psm1 and .psd1 files.

MyModule/
│
├── MyModule.psm1
└── MyModule.psd1

Step 3: Writing the Module Content

With the directory structure in place, it’s time to write the module content! In the MyModule.psm1 file, include all your function definitions. For example, here is a function named Get-Greeting that displays a greeting. Include as many functions as needed for your project.

function Get-Greeting {
    param(
      [string]$Name = "World"
    )
    "Hello, $Name!"
}

Read More: PowerShell Advanced Functions: Getting Started Guide

Step 4: Writing the Module Manifest

The .psd1 file is a PowerShell hash table that includes metadata and configuration details for your module. Here’s what to include:

• Root module file name
• Author
• Description
• Version
• PowerShell version
• Functions to export

Below is an example MyModule.psd1:

@{
    RootModule        = 'MyModule.psm1'
    ModuleVersion     = '1.0.0'
    Author            = 'Your Name'
    Description       = 'A custom PowerShell module example'
    PowerShellVersion = '7.0'
    FunctionsToExport = 'Get-Greeting'
    CmdletsToExport   = @()
    AliasesToExport   = @()
}

You can also use the New-ModuleManifest cmdlet to generate this file for you. Using this cmdlet generates additional information not included above for more advanced customization. Here is an example that produces the same content as the sample MyModule.psd1 file above:

New-ModuleManifest `
    -Path MyModule.psd1 `
    -RootModule MyModule.psm1 `
    -ModuleVersion 1.0.0 `
    -Author "Your Name" `
    -Description "A custom PowerShell module example." `
    -FunctionsToExport @('Get-Greeting') `
    -PowerShellVersion 7.0

Step 5: Adding the Module to Your System

PowerShell auto-imports modules when they exist on specific paths in your system. These paths vary depending on the PowerShell version and operating system. To test the custom module, place the module directory created in Step 2 in a user-scoped or system-scoped path. PowerShell stores module paths in the environment variable $env:PSModulePath.

Read More: about_PSModulePath

Consider who needs access when choosing between the user and system scope for a PowerShell module. If the module is for personal use or during development and testing, install it in the user scope to avoid requiring administrative privileges and keep it private.

The system scope is more appropriate for shared environments or team workflows where multiple users need access, though it requires admin rights. For flexibility, you can develop the module in the user scope and deploy it to the system scope once it is stable.

For user-scoped paths, review the table below and choose the option that fits your scenario:

For system-scoped paths, review the table below and choose the option that fits your scenario:

Once you save the module into one of the PowerShell module paths, you can test your module import one of two ways:

1. Open a new PowerShell terminal and verify one of your module’s available commands.
2. Use an existing PowerShell terminal and the Import-Module command along with your module name.

You can view module information using the Get-Module cmdlet. When piping the results to Format-Listing, notice the Description and Version fields match information from the .psd1 file.

Summary

Creating a custom PowerShell module enhances code organization, promotes reusability, and simplifies sharing. Following this guide, you’ve learned how to create a PowerShell module with the necessary core files, structure it properly, and define pertinent metadata in the manifest. With your custom module, you can streamline your PowerShell scripts and share your work with others.

Whether you’re automating tasks for your team or publishing modules for the broader PowerShell community, this skill is valuable to your toolkit. Start building your module today and take your scripting to the next level!