Module Discovery, Import, Autoloading, and PSModulePath

1. A module is a boundary for reusable PowerShell tooling

By Chapter 14 you can write functions and scripts that perform useful work locally and remotely. The next engineering problem is organization: how do several related commands travel together, avoid leaking helper details, declare a version, and become discoverable without copying files into every script?

A module is PowerShell's packaging and namespace boundary for related commands and resources. A module can contain functions, cmdlets, variables, aliases, classes, format/type data, help, assemblies, and metadata. Consumers import the module and use its public commands instead of knowing how every internal file is arranged.

2. Loaded and available are different states

Get-Module answers “what modules are loaded in this session?” while Get-Module -ListAvailable searches known module locations and answers “what could I load?” This distinction matters when debugging why a command is missing or why a stale version is still active.

# Loaded in the current session only.
Get-Module | Sort-Object Name,Version

# Discoverable on disk, even if not loaded.
Get-Module -ListAvailable |
    Sort-Object Name,Version |
    Select-Object Name,Version,Path,CompatiblePSEditions

A module being installed does not mean it is loaded. Conversely, a loaded module can remain usable after its source files are changed until you explicitly reload it or start a new session.

3. Autoloading makes installed commands feel built in

PowerShell normally uses module autoloading. If a module is stored in a discoverable location, asking for one of its commands can cause PowerShell to import the module automatically. You often do not need a profile full of Import-Module calls.

# Exact command discovery can trigger module autoloading.
Get-Command ConvertTo-Json
Get-Module Microsoft.PowerShell.Utility

# Wildcard discovery does not autoload every matching module.
Get-Command '*Json*' | Select-Object Name,CommandType,Source

This design reduces startup work. It also means command discovery itself can change the set of modules loaded in the session, so inspect Get-Module when reproducing subtle session behavior.

4. Import-Module controls how a module enters the session

Use Import-Module when you need a specific module, a specific version, a nonstandard path, or import options such as -NoClobber. Remove-Module removes the module from the current session; it does not uninstall the module from disk.

$module = Get-Module -ListAvailable Microsoft.PowerShell.Utility |
    Sort-Object Version -Descending |
    Select-Object -First 1

Import-Module -ModuleInfo $module -Verbose
Get-Module Microsoft.PowerShell.Utility
Remove-Module Microsoft.PowerShell.Utility

# The module is still installed/discoverable.
Get-Module -ListAvailable Microsoft.PowerShell.Utility |
    Select-Object -First 1 Name,Version,Path

5. PSModulePath is PowerShell’s module search path

$Env:PSModulePath is a platform path list. PowerShell searches these locations for module folders and module files. Do not split it with a hard-coded semicolon: Windows and Unix-like systems use different path separators. .NET exposes the correct separator through [IO.Path]::PathSeparator.

$modulePaths = $env:PSModulePath -split [IO.Path]::PathSeparator
$modulePaths | ForEach-Object {
    [pscustomobject]@{
        Path   = $_
        Exists = Test-Path -LiteralPath $_ -PathType Container
    }
}

Windows PowerShell 5.1 uses WindowsPowerShell\Modules paths instead. That is one reason blindly copying modules between editions can create compatibility problems.

6. Discover commands by module instead of guessing names

Modules are useful discovery units. Once you know the module, you can list the commands it exposes and inspect their metadata before running anything.

Get-Command -Module Microsoft.PowerShell.Utility |
    Sort-Object Noun,Verb |
    Select-Object Name,CommandType,Version,Source

Get-Command ConvertTo-Json |
    Select-Object Name,ModuleName,Version,Parameters

Get-Command, Get-Help, and module metadata form a discoverability contract. A team module should make its public surface easy to enumerate without reading private source files.

7. Command-name conflicts are real namespace collisions

Two modules can export a command with the same name. The command that wins normal name resolution depends on what was imported and in what order. Production scripts should not silently depend on accidental import order.

# Protect existing commands when importing a third-party module.
# Import-Module SomeModule -NoClobber

# Module-qualified invocation identifies the exact source.
Microsoft.PowerShell.Utility\ConvertTo-Json -InputObject @{ Status='ok' }

# Inspect every visible command with the same name.
Get-Command ConvertTo-Json -All |
    Select-Object Name,CommandType,Source,Version

Import-Module -Prefix is another conflict-management tool: it adds a prefix to imported command nouns for the current session. Prefer stable, distinctive nouns in your own modules so consumers rarely need this escape hatch.

8. Multiple installed versions require an explicit version policy

PowerShell can discover multiple versions of the same module. By default, normal discovery/import generally prefers the highest available version that meets constraints. A production script that depends on a specific API should state its compatibility requirement rather than assuming “newest means compatible.”

Get-Module -ListAvailable |
    Group-Object Name |
    Where-Object Count -gt 1 |
    ForEach-Object {
        $_.Group | Sort-Object Version -Descending |
            Select-Object Name,Version,Path
    }

# Example exact import pattern when your application requires it:
# Import-Module -FullyQualifiedName @{
#     ModuleName      = 'Contoso.Tools'
#     RequiredVersion = '2.4.1'
# }

9. Windows PowerShell Compatibility is implicit remoting, not native compatibility

On Windows, PowerShell 7 can use selected Windows PowerShell 5.1 modules through the Windows PowerShell Compatibility feature. Import-Module -UseWindowsPowerShell starts or reuses a background Windows PowerShell 5.1 session named WinPSCompatSession and exposes proxy commands through implicit remoting.

This mechanism only works locally on Windows and requires Windows PowerShell 5.1. Parameters and results cross a serialization boundary, so returned complex objects can be deserialized snapshots rather than live native objects—exactly the remoting concept from Chapter 14.

# Inspect support without importing a legacy module.
$import = Get-Command Import-Module
$hasWinCompat = $import.Parameters.ContainsKey('UseWindowsPowerShell')

[pscustomobject]@{
    IsWindows              = $IsWindows
    HasUseWindowsPowerShell = $hasWinCompat
    WindowsPowerShell51    = if ($IsWindows) {
        [bool](Get-Command powershell.exe -ErrorAction SilentlyContinue)
    } else { $false }
}

Do not reach for -SkipEditionCheck as a universal fix. Microsoft explicitly warns that a module can import and still fail later when it calls APIs unavailable to PowerShell 7.

10. Lab: build a read-only module inventory

This lab changes no system files. It turns raw module discovery into a reusable inventory object that shows loaded state, location, and edition metadata.

$loadedByName = @{}
Get-Module | ForEach-Object { $loadedByName[$_.Name] = $_.Version }

$inventory = Get-Module -ListAvailable |
    Sort-Object Name,Version -Descending |
    ForEach-Object {
        [pscustomobject]@{
            Name               = $_.Name
            Version            = $_.Version.ToString()
            LoadedVersion      = if ($loadedByName.ContainsKey($_.Name)) {
                $loadedByName[$_.Name].ToString()
            } else { $null }
            CompatibleEditions = @($_.CompatiblePSEditions) -join ','
            Path               = $_.Path
        }
    }

$inventory | Select-Object -First 20
$inventory | Group-Object Name | Where-Object Count -gt 1 |
    Select-Object Name,Count

11. Common mistakes and what they reveal

12. Why module discovery matters in DevOps

CI runners, admin workstations, containers, jump hosts, and developer laptops rarely have identical module inventories. A deployment script should be able to state “I require module X in version range Y” and fail with evidence when the requirement is not met. Modules make that dependency explicit and inspectable.

They also reduce copy/paste drift: instead of embedding the same helper functions in twenty pipeline scripts, a team can version one module and update consumers deliberately.

13. Verification checklist

• You can explain the difference between loaded and available modules.
• You can inspect $Env:PSModulePath portably.
• You understand module autoloading and why wildcard discovery behaves differently.
• You can identify the source module for a command and use module-qualified invocation.
• You know that Remove-Module is not an uninstall operation.
• You can describe Windows PowerShell Compatibility as a local Windows implicit-remoting bridge with serialization limits.

14. Knowledge check

15. Summary and next bridge

Modules are discoverable, versioned command boundaries. PowerShell searches PSModulePath, can autoload commands on demand, and gives you explicit import controls when versioning or name conflicts matter. Legacy Windows modules can sometimes be bridged through WinCompat, but that bridge is remoting—not proof of native compatibility.

Lesson 2 now builds a script module from functions you control, so public exports, private helpers, module scope, and reload behavior become concrete.

16. Authoritative references

• Microsoft Learn — about_Modules
• Microsoft Learn — about_PSModulePath
• Microsoft Learn — Import-Module
• Microsoft Learn — Windows PowerShell Compatibility