Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 34 ยท Functions and Scripts

Modules and Profiles

Learn how PowerShell modules are found, imported and installed from the Gallery, how to write a simple .psm1 module, and how to customize $PROFILE.

You have written functions and saved them in scripts. The next step is to package them so they load with one command, hide their private helpers and can be shared. That package is a module. PowerShell itself is made of modules: every cmdlet you have used comes from one, and thousands more are available from the PowerShell Gallery.

This lesson covers finding and importing modules, installing them from the Gallery, writing a small module of your own, and using your profile script to customize every session. The PowerShell here is read-only because the site has no PowerShell host or network access to the Gallery. The runnable examples are JavaScript stand-ins that model module search and export rules, and they are labeled as models.

What a module is

A module is a folder (or single file) that groups commands, and sometimes variables, aliases and data. The most common kind is a script module: a .psm1 file full of functions, often with a manifest .psd1 file that describes it. Modules give you three things scripts do not:

  • A namespace for exports. Only the functions you choose are visible. The rest stay private.
  • Automatic loading. Calling a command from an installed module loads it for you.
  • Versioning and sharing. A manifest records the version, author and dependencies.

Finding and importing modules

PowerShell looks for modules in the folders listed in $env:PSModulePath. Each entry holds module folders such as MyTools\MyTools.psm1.

POWERSHELL
Get-Module                          # modules loaded in this session
Get-Module -ListAvailable           # modules PowerShell can find on disk
Get-Command -Module Microsoft.PowerShell.Management   # commands in one module
$env:PSModulePath -split [IO.Path]::PathSeparator     # the search folders

You rarely need Import-Module for installed modules. Since PowerShell 3, auto-loading imports a module the first time you call one of its commands. You still use Import-Module to load a module from a specific path, to control which commands you import, or to reload a module after you edit it.

POWERSHELL
Import-Module Pester
Import-Module .\MyTools.psm1 -Force       # -Force reloads after changes
Import-Module Pester -Prefix Test         # commands become Invoke-TestPester
Remove-Module MyTools                     # unload from the session

Name clashes

If two modules export the same command name, the one imported last wins. Use -Prefix or the fully qualified name ModuleName\Command to be explicit.

Anatomy of a module

.psm1 The script file that holds the functions.
.psd1 A manifest with version, author and exports.
Folder name Must match the module name and sit on PSModulePath.

Private helpers stay hidden unless you export them.

1 / 2

The PowerShell Gallery is the public package repository for modules and scripts. Two toolsets install from it. The older PowerShellGet module provides Find-Module and Install-Module. The newer PSResourceGet module, called Microsoft.PowerShell.PSResourceGet, provides Find-PSResource and Install-PSResource, and ships with PowerShell 7.4 and later. Both do the same job. The commands are:

POWERSHELL
# PowerShellGet
Find-Module -Name Pester
Install-Module -Name Pester -Scope CurrentUser
Update-Module -Name Pester
Uninstall-Module -Name Pester

# PSResourceGet
Find-PSResource -Name Pester
Install-PSResource -Name Pester -Scope CurrentUser
Update-PSResource -Name Pester

Use -Scope CurrentUser to install into your own folder without administrator rights. The first time you install from the Gallery, PowerShell asks whether you trust the repository, because it is marked untrusted by default. Anyone can publish there, so treat an install like running the author's code with your own rights.

Before installing an unfamiliar module:

  1. Check the author, download count and project page.
  2. Read the code if it is small, or the release notes if it is large.
  3. Pin a version with -RequiredVersion in scripts so an update cannot change behavior unexpectedly.
  4. Prefer well known modules from organizations you recognize.

This stand-in models the module search order. A module is found in the first folder of the search path that contains a matching name, and the loaded copy is cached so a second import does nothing.

JS A module search path model

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The folder list and the cache are a model. Real PowerShell also compares versions and prefers the highest one when several are installed side by side.

Writing a simple module

A module can be one file. Create a folder named after the module in a location on $env:PSModulePath (for example Documents\PowerShell\Modules for PowerShell 7 on Windows) and put a .psm1 file with the same name inside.

POWERSHELL
# Documents\PowerShell\Modules\TextTools\TextTools.psm1

function ConvertTo-Slug {
    [CmdletBinding()]
    param([Parameter(Mandatory, ValueFromPipeline)][string]$Text)
    process {
        (Remove-Noise $Text.ToLower().Trim()) -replace '\s+', '-'
    }
}

function Remove-Noise {
    param([string]$Text)
    $Text -replace '[^a-z0-9\s-]', ''
}

Export-ModuleMember -Function ConvertTo-Slug

Here ConvertTo-Slug is the public command and Remove-Noise is a private helper. Export-ModuleMember lists what leaves the module. If you omit it, every function in a .psm1 is exported, so the explicit list is a good habit.

POWERSHELL
Import-Module TextTools
'Hello, World 2026' | ConvertTo-Slug      # hello-world-2026
Remove-Noise 'x'                          # error: not recognized (private)

To describe the module, add a manifest. New-ModuleManifest writes a .psd1 with the version, author and exports, and Test-ModuleManifest checks it.

POWERSHELL
New-ModuleManifest -Path .\TextTools\TextTools.psd1 `
    -RootModule 'TextTools.psm1' `
    -ModuleVersion '1.0.0' `
    -Author 'Ada' `
    -FunctionsToExport 'ConvertTo-Slug'
Test-ModuleManifest .\TextTools\TextTools.psd1

Listing functions by name in the manifest, instead of using *, also lets PowerShell auto-load the module faster, because it can read the list without running the code.

Once you edit a module, re-import it with Import-Module TextTools -Force, otherwise the session keeps the old copy.

The model below shows exports and private helpers. A module is a function that builds its members privately and returns only the exported ones, much like a closure.

JS Public exports and private helpers

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Profiles

A profile is a script that PowerShell runs when it starts an interactive session. Use it for aliases, helper functions, a custom prompt and module imports you want everywhere.

The variable $PROFILE holds the path of the profile for the current user and the current host (for example the console or VS Code). It also has properties for the other four profile files.

POWERSHELL
$PROFILE                              # current user, current host
$PROFILE.CurrentUserAllHosts          # current user, every host
$PROFILE.AllUsersCurrentHost          # all users, this host (needs admin to edit)
$PROFILE.AllUsersAllHosts

Test-Path $PROFILE                    # does it exist yet?
New-Item -Path $PROFILE -ItemType File -Force    # create it, with folders
notepad $PROFILE                      # or: code $PROFILE

PowerShell 7 and Windows PowerShell 5.1 use separate profile folders on Windows (Documents\PowerShell and Documents\WindowsPowerShell), so a profile written for one does not affect the other. A profile does not exist until you create it.

A small profile might look like this:

POWERSHELL
Set-Alias -Name ll -Value Get-ChildItem
function Edit-Profile { code $PROFILE }
function prompt { "$(Split-Path -Leaf (Get-Location))> " }
Import-Module Terminal-Icons -ErrorAction SilentlyContinue

Keep it fast and quiet. Everything in the profile runs on each start, so slow network calls or noisy output make every new window annoying. Start a session without it using pwsh -NoProfile, which is also the right way to test whether a problem comes from your profile. Because the profile runs with your rights, never paste in code you have not read.

Do not rely on a profile inside scripts. Scheduled tasks and other automation often run with -NoProfile, so a script that needs a function from your profile will fail there. Put shared code in a module and import it explicitly.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does $env:PSModulePath contain?

    PSModulePath is a list of folders. Each holds module folders, and PowerShell searches them in order.
  2. 2. You edited MyTools.psm1 and want the current session to use the new code. What do you run?

    Import-Module -Force reloads the module. Without it, the session keeps the copy that is already loaded.
  3. 3. In a .psm1 file, how do you keep a helper function private?

    Only what you export leaves the module. Functions that are not exported stay private to the module.
  4. 4. Which command installs a module from the PowerShell Gallery for your user only, with the newer PSResourceGet tools?

    Install-PSResource is the PSResourceGet command. The older PowerShellGet equivalent is Install-Module.
  5. 5. Why should a script not depend on functions defined in your profile?

    Profiles run only for interactive sessions that load them. Put shared code in a module and import it.

Summary

  • A module packages commands, hides private helpers and can carry a manifest with version and author.
  • PowerShell searches the folders in $env:PSModulePath. Installed modules auto-load, and Import-Module -Force reloads one you edited.
  • Install from the PowerShell Gallery with Install-Module (PowerShellGet) or Install-PSResource (PSResourceGet), using -Scope CurrentUser. Review what you install.
  • A simple module is a folder with a .psm1 of the same name plus Export-ModuleMember or a manifest for the public list.
  • $PROFILE points to the script that runs at the start of interactive sessions. Keep it fast, and use -NoProfile for automation and troubleshooting.

Next, put these skills to work on real data with Working with Files and Folders.