Building and Importing Your Own PowerShell Modules

What Is a PowerShell Module?

A module is a self-contained, reusable unit that packages functions, and optionally variables, aliases, and other resources, into one thing PowerShell can load as a whole. Instead of pasting the same helper function into every script, or dot-sourcing a loose collection of .ps1 files with brittle relative paths, the functions live in one folder that PowerShell already knows how to discover.

Think of a module as a labelled toolbox kept in one place, rather than tools scattered loose across a desk, a colleague’s desk, and half a dozen one-off scripts. Once the toolbox exists, anyone who needs a tool from it just opens the lid; they do not need to know which script originally wrote the function, or copy-paste it again.

A module has two core files: the .psm1 script module file, which contains the actual function code, and the .psd1 manifest, a hashtable of metadata describing the module’s version, author, and what it exports. A manifest is optional, since PowerShell only requires the .psm1, but almost every module worth reusing has one, because it is also where export restrictions and version requirements are declared.

Why Package Functions Into a Module?

A function that only lives in a PowerShell profile or a script someone dot-sources works, right up until it needs to be reused by someone else, run from a scheduled task under a different account, or kept under source control alongside a version number.

None of this requires publishing anything to a gallery. A module is useful the moment it is a folder with a consistent name sitting in a path PowerShell already searches. Publishing to a feed like the PowerShell Gallery is a separate, later step.

Why Ops Teams Care About Modules

Every environment that has been managed with PowerShell for more than a year or two accumulates the same problem: the same helper function, slightly different, pasted into a dozen scripts on a dozen servers. One copy gets a bug fix, the other eleven do not, and nobody can say with confidence which version is running where.

A module fixes the source of that drift rather than treating each symptom. One folder, one version number, one place to fix a bug once. Dropping it into a source-controlled repository means every change is tracked, and rolling it out to a server is a file copy rather than a rewrite.

Building the Module

The .psm1 file holds the function definitions, exactly as they would appear in any script, plus one line at the end that controls what gets exported.

# ADOpsToolkit.psm1

function Get-StaleComputerAccount {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [int]$InactiveDays
    )

    $cutoff = (Get-Date).AddDays(-$InactiveDays)
    Get-ADComputer -Filter * -Properties LastLogonTimestamp |
        Where-Object { [datetime]::FromFileTime($_.LastLogonTimestamp) -lt $cutoff }
}

function Find-LockedOutUser {
    [CmdletBinding()]
    param ()

    Search-ADAccount -LockedOut
}

# Only these two functions are visible outside the module.
# Anything else defined above is a private helper.
Export-ModuleMember -Function Get-StaleComputerAccount, Find-LockedOutUser

The manifest is generated separately with New-ModuleManifest, which writes a .psd1 file next to the .psm1. Only Path is mandatory; every other parameter has a documented default if left out.

# Generates ADOpsToolkit.psd1 alongside the .psm1 in the same folder
New-ModuleManifest -Path '.\ADOpsToolkit\ADOpsToolkit.psd1' `
    -RootModule 'ADOpsToolkit.psm1' `
    -ModuleVersion '1.0.0' `
    -Author 'K Shankar R Karanth' `
    -Description 'Reusable AD operations helper functions' `
    -FunctionsToExport @('Get-StaleComputerAccount', 'Find-LockedOutUser')

Importing, Reloading, and Testing the Module

Whether Import-Module is needed at all depends on where the folder sits. A module placed under one of the paths in $env:PSModulePath autoloads the first time a command from it is used, with no explicit import required. A module anywhere else needs a manual import with a path.

# Create the module folder under the current user's module path -
# Windows PowerShell 5.1 uses the WindowsPowerShell\Modules subfolder
New-Item -Path "$HOME\Documents\WindowsPowerShell\Modules\ADOpsToolkit" -ItemType Directory

# Write the function code into the .psm1
# (in practice this is an editor, not New-Item -ItemType File, but the file must exist first)
New-Item -Path "$HOME\Documents\WindowsPowerShell\Modules\ADOpsToolkit\ADOpsToolkit.psm1" -ItemType File

# Generate the manifest alongside it
New-ModuleManifest -Path "$HOME\Documents\WindowsPowerShell\Modules\ADOpsToolkit\ADOpsToolkit.psd1" `
    -RootModule 'ADOpsToolkit.psm1' -ModuleVersion '1.0.0'

# Because the module now sits under $env:PSModulePath, this line is optional -
# calling Get-StaleComputerAccount directly would autoload it. -Verbose shows what loaded.
Import-Module ADOpsToolkit -Verbose

# During development, reload the module after editing the .psm1
Import-Module ADOpsToolkit -Force

# Confirm PowerShell can see the module and list what it exports
Get-Module -ListAvailable ADOpsToolkit
Get-Command -Module ADOpsToolkit

# Validate the manifest's own syntax without importing anything
Test-ModuleManifest -Path "$HOME\Documents\WindowsPowerShell\Modules\ADOpsToolkit\ADOpsToolkit.psd1"

# See every path PowerShell searches for modules, one per line
$env:PSModulePath -split ';'

# Unload the module from the current session (this does not delete or uninstall it)
Remove-Module ADOpsToolkit

Module Locations Cheat Sheet

The default locations differ between PowerShell 7+ and Windows PowerShell 5.1, though both are automatically included in $env:PSModulePath, so a module dropped in the matching folder for the engine in use is discoverable without any extra configuration.

Troubleshooting Cheat Sheet

Final Thoughts

None of this is complicated once the two rules are clear: the folder name has to match the file inside it, and Export-ModuleMember decides what leaves the module, not what the file happens to define. Everything else exists to make those two rules discoverable without reading documentation every time: the manifest keys, the module paths, autoloading.

The functions that end up inside a module are exactly the ones worth turning into advanced functions first. Parameter validation and a correct process block matter more once a function is shared across a team than they ever do in a one-off script.