🎓 A1Learner
🔍
0 of 47 lessons completed

PowerShell Module Paths

The module path is the list of folders PowerShell searches when a module is imported by name. A module in one of those folders can be imported without a file path.

Add the folder to the module path

Adding the script folder to the module path lets PowerShell find the module by name. The import then needs no file path.

$folder = Join-Path $PSScriptRoot "PathTool"
$null = New-Item -ItemType Directory -Path $folder -Force
Set-Content -Path (Join-Path $folder "PathTool.psm1") -Value @'
function Get-PathMessage { "Found by name" }
Export-ModuleMember -Function Get-PathMessage
'@
$env:PSModulePath = $PSScriptRoot + ":" + $env:PSModulePath
Import-Module PathTool
Get-PathMessage

List what the path now finds

Listing the module by name proves the path change worked. The module appears because its folder is now searched.

$folder = Join-Path $PSScriptRoot "PathTool"
$null = New-Item -ItemType Directory -Path $folder -Force
Set-Content -Path (Join-Path $folder "PathTool.psm1") -Value @'
function Get-PathMessage { "Found by name" }
Export-ModuleMember -Function Get-PathMessage
'@
$env:PSModulePath = $PSScriptRoot + ":" + $env:PSModulePath
Get-Module -ListAvailable -Name PathTool | Select-Object -ExpandProperty Name

Name lookup needs the path first

Before the path is added, importing by name fails. After the path is added, the same import works.

$folder = Join-Path $PSScriptRoot "PathTool"
$null = New-Item -ItemType Directory -Path $folder -Force
Set-Content -Path (Join-Path $folder "PathTool.psm1") -Value @'
function Get-PathMessage { "Found by name" }
Export-ModuleMember -Function Get-PathMessage
'@
try { Import-Module PathTool -ErrorAction Stop } catch { "Caught: " + $_.Exception.Message }
$env:PSModulePath = $PSScriptRoot + ":" + $env:PSModulePath
Import-Module PathTool
Get-PathMessage

Example

$folder = Join-Path $PSScriptRoot "PathTool"
$null = New-Item -ItemType Directory -Path $folder -Force
Set-Content -Path (Join-Path $folder "PathTool.psm1") -Value @'
function Get-PathMessage { "Found by name" }
Export-ModuleMember -Function Get-PathMessage
'@
try { Import-Module PathTool -ErrorAction Stop } catch { "Caught: " + $_.Exception.Message }
$env:PSModulePath = $PSScriptRoot + ":" + $env:PSModulePath
Get-Module -ListAvailable -Name PathTool | Select-Object -ExpandProperty Name
Import-Module PathTool
Get-PathMessage

Key points

  • Module path: the list of folders PowerShell searches when a module is imported by name.
  • PSModulePath: the environment variable that holds the module path.
  • In-script change: assigning a new value to $env:PSModulePath in a script changes it only for that running script.
  • Folder rule: the path entry must be the folder that holds the module folder, not the module file itself.
  • Name import: Import-Module with just a module name searches the module path instead of a file path.

In this example, the script first builds the module and tries importing it by name, which fails. It then adds the script folder to the module path, lists the module by name to prove discovery, imports it by name, and calls its function.

Note

the colon separates one path entry from the next in the module path value.

Try it Yourself

Edit the code, then press Run.

Running is simulated

Exercise

What does adding the script folder to $env:PSModulePath change?