Core Skills Level: Intermediate Chapter 6: Toolboxes You Can Load When You Need Them
Import a module and build a custom module
Import-Module loads a module into your session. A custom module is simply your own functions saved in a .psm1 file, with a manifest that describes them.
Lesson 2 of 2 in Chapter 6: Toolboxes You Can Load When You Need Them. Previous step in this path: What is a module. 3 learning objectives, 10 examples, and a knowledge check.
Start: what you will learn
Import-Module loads a module into your session. A custom module is simply your own functions saved in a .psm1 file, with a manifest that describes them.
Learning objectives
- Import a module into a session
- Explain what a .psm1 file and a manifest do
- Build a small custom module with one function
Concept in simple words
What it is: Import-Module loads a module into your current session, so its commands become available to use. A custom module is a module you build yourself, usually as a .psm1 file holding your own functions. A manifest, a .psd1 file, describes that module, with its name, version, author, and which functions to export, meaning which functions other people may use.
Why it works
Why it works this way: a session starts with only some modules loaded, and importing adds the rest for that session only. When you close PowerShell, the import is gone, and you import again next time. That session only behaviour keeps sessions clean, and it is why a script should import what it needs at the top, so the script says its own requirements plainly. Anyone reading the script can see the toolbox it needs, before the script does any real work.
Think of it like this
Think of it like this: importing a module is like opening a toolbox and laying its tools on your bench. The tools are yours to use while you work, but when you pack up and leave, they go back in the box. A custom module is a toolbox you built yourself, with tools shaped for jobs you do often, and a manifest is the label on the box saying what is inside, who made it, and which version it is.
What happens behind an import: when you run Import-Module, PowerShell finds the module files, reads the module code or manifest, and adds the exported commands to your session. Exported means made available for you to call. Commands that are not exported stay inside the module, where only the module own code can use them. That boundary is useful. It lets you keep helper code private, while sharing only the clean tools you want others to use.
Import by name, and import by path: if a module lives in a folder listed in $env:PSModulePath, you can import it by name alone, such as Import-Module ActiveDirectory. If a module lives somewhere else, such as a file on your desktop or in a project folder, you must import it by path, such as Import-Module .\MyTools.psm1. The path tells PowerShell exactly where to look, because the module path search cannot find it on its own. The dot and backslash at the start of .\MyTools.psm1 simply mean, in the current folder.
A quiet import: by default, Import-Module shows no output when it succeeds. Silence here means success, not failure, as long as no error appears. That quiet behaviour can confuse a beginner, who expects a confirmation message. If you want proof, add -PassThru, which returns the imported module object, or run Get-Module with the module name straight after the import. Both checks are shown in the examples below. Do not mistake no output for no import.
How it works, step by step
How it works, step by step, in order: first, check that the module is installed, with Get-Module -ListAvailable -Name, or check that your own file exists, before you try to import it. Second, import a built in module by name, such as Import-Module ActiveDirectory. Third, confirm the import with Get-Module and the module name. Fourth, use its commands in the same session. Fifth, for your own module, save your functions in a .psm1 file, and import it by path. Sixth, test one function with a small, safe input. Seventh, if you plan to share the module, add a .psd1 manifest describing it, and export only the functions others should use.
Building a custom module, step by step: first, choose one clear area for the module, such as greeting messages or small reporting helpers. Second, write one or two functions in a .psm1 file, each with a clear Verb-Noun name and a param block for its inputs. Third, decide which functions are public and which are helpers. Fourth, add Export-ModuleMember -Function with only the public names, so helpers stay private. Fifth, import the file by path and test each public function. Sixth, fix any mistakes in the file, then reload with -Force, because the session still holds the old copy until you reload it.
The manifest, in depth: a manifest is a .psd1 data file holding a hash table, which is a set of named settings and values. New-ModuleManifest creates that file for you, so you do not have to write every setting by hand. The most important settings for a beginner are RootModule, which points to the .psm1 file that holds the code, ModuleVersion, which gives the version number, Author and Description, which say who made it and what it does, and FunctionsToExport, which lists the public functions. When a manifest is present, PowerShell uses the manifest to decide what to load and what to export, so the manifest and the .psm1 file must agree on the function names.
Versions and reloading, in plain words: ModuleVersion is how you tell version 1.0.0 apart from a later fix. When you raise the version after a change, other people can tell that something changed, and they can ask for a particular version if they need the older behaviour. Import-Module supports -RequiredVersion for one exact version, and -MinimumVersion for that version or newer. After you edit a .psm1 file, use Import-Module with -Force to reload it in the same session. Without -Force, PowerShell may keep the old loaded copy, and your fix will seem to have no effect, which is a common and confusing mistake.
Name clashes, in plain words: two modules can provide a command with the same name. By default, the newly imported command can hide, or clobber, the older one with the same name in your session. Import-Module gives you two calm ways to handle that. The -NoClobber parameter refuses to import a command that would hide an existing command. The -Prefix parameter adds a prefix to the imported command names, so they stay unique, for example by turning Get-Greeting into Get-CustGreeting when you use -Prefix Cust. If you only need one function from a module, you can also use -Function with that function name, so you import less and clash less.
Removing a module, in plain words: Remove-Module unloads a module from your current session. It removes its commands from that session, but it does not uninstall the module and it does not delete any files from the computer. That makes it a safe way to tidy a session, or to test what happens without a module. If you want the module back, you simply import it again. Think of Remove-Module as putting the tools back in the box, not throwing the box away.
Worked walkthrough, example 1: in Import-Module ActiveDirectory followed by Get-ADUser -Filter * -ResultSetSize 5 | Select-Object Name, the import loads the directory commands for this session. Get-ADUser then asks for users, with -Filter * meaning all users, and -ResultSetSize 5 limiting the result to five. Select-Object keeps only Name. Look at the output and check that the import came first, because without it the Get-ADUser command would not be available in a session where automatic loading did not already load it. The limit of five matters here. It keeps a read only directory query small and easy to check, instead of returning every user at once.
Worked walkthrough, example 2: in the MyTools.psm1 file, the first line is a comment naming the file, so a reader knows what file they are looking at. Then function Get-Greeting defines a function with a clear Verb-Noun name. Inside it, param([string]$Name) says the function takes one input, called $Name, and that input should be text. The last line, "Hello, $Name", builds the greeting text, with $Name replaced by the value you pass in. This code on its own only defines the file contents. It does not run the greeting until you import the file and then call Get-Greeting, which the next example shows.
Worked walkthrough, example 3: in Import-Module .\MyTools.psm1 followed by Get-Greeting -Name Izaz, the first line imports your own file by path, because a file in your current folder is not found by name alone through the module path. The second line calls the function you just imported, with -Name Izaz giving a value to the $Name input. Look at the output and check that the greeting uses the name you passed in. If you change Izaz to another name, only the greeting changes, which proves the input is flowing through the param block as intended.
Worked walkthrough, example 4: in Import-Module ActiveDirectory followed by Get-Module ActiveDirectory, Import-Module ActiveDirectory loads the directory commands into your current session. Get-Module ActiveDirectory then asks for that loaded module by name, so you can confirm the import worked. The output shows the module name and version, which is a quick check before you use its commands. If Get-Module shows nothing for that name, the import did not take effect in this session, and you should check the module name and the installed list before going further.
Worked walkthrough, example 5: in Import-Module Microsoft.PowerShell.Management -PassThru | Select-Object Name, Version, the -PassThru parameter asks Import-Module to return the imported module object, instead of staying silent. The pipe sends that object onward. Select-Object keeps only Name and Version, so you get a short confirmation line. Use this form when you want the import itself to prove it worked, in one command, rather than running a second check command afterwards. If you remove -PassThru, a successful import shows no output at all.
Worked walkthrough, example 6: in Import-Module .\MyTools.psm1 -Force, the -Force parameter reloads the module even though it is already loaded. This is the command to use after you edit the .psm1 file and save it. Without -Force, your open session keeps the older copy, so your fix will not appear when you call the function again. Look for the change in behaviour after the reload, not before it. If the function still behaves the old way, check that you saved the file, and that you reloaded the same path you edited.
Worked walkthrough, example 7: in the second MyTools.psm1 file, there are two functions. Get-Greeting is the public tool, and Format-GreetingText is a helper that builds the text. The last line, Export-ModuleMember -Function Get-Greeting, says only Get-Greeting is exported. That means after import, you can call Get-Greeting, but Format-GreetingText stays private to the module. If you change the export list to include the helper, the helper becomes callable too, which is fine for testing, but it also makes the public surface larger, so keep the export list small on purpose.
Worked walkthrough, example 8: in New-ModuleManifest -Path .\MyTools.psd1 -RootModule MyTools.psm1 -ModuleVersion 1.0.0 -Author "Your Name" -Description "Small greeting tools." -FunctionsToExport Get-Greeting, each part has one job. -Path says where to write the new manifest file. -RootModule points to the .psm1 file that holds the code. -ModuleVersion sets the version. -Author and -Description fill in the label. -FunctionsToExport lists the public function. Warning: this command writes a new file on disk, so check the path before you run it, and run it in the folder where your module files live. After it runs, you can check the result with Test-ModuleManifest -Path .\MyTools.psd1, which validates the manifest and reports problems instead of silently accepting a broken file.
Worked walkthrough, example 9: in Get-Command -Module MyTools | Select-Object Name, CommandType, the -Module parameter asks for the commands inside your own module, after you have imported it. Select-Object keeps Name and CommandType, so you can see the public surface at a glance. Look for Get-Greeting in the list, and check that a private helper is not listed, if you used Export-ModuleMember to keep it private. If the list is empty, check that the import succeeded, and that you spelled the module name the same way in both commands.
Worked walkthrough, example 10: in Remove-Module MyTools, the command unloads your module from the current session. It does not delete MyTools.psm1, and it does not uninstall anything. After this command, Get-Greeting is no longer available in this session, until you import the module again. Use this when you want a clean session, or when you want to prove to yourself that a command really came from that module, because removing the module should make that command unavailable again.
When to use it
When to use it, and when not to: use an explicit import in scripts, so anyone reading the script can see what it depends on, and keep custom modules small and focused, one area per module. Do not build one giant module for everything, and do not import a module inside a script without checking that it exists on the computer where the script will run, or the script will fail far from home. Do not import a module from a source you do not trust, because importing runs the module code in your session. Listing and reading are safe. Importing is a step that deserves a trusted source.
Safety note, please read this before you change anything: the listing commands in this chapter change nothing, and they are safe to practise. Import-Module and Remove-Module change only your current session, not the files on disk, so they are also low risk, as long as you trust the module source. New-ModuleManifest writes a new file, and editing a .psm1 file changes that file, so check the path first, and keep a copy of a working file before you edit it. Installing a module, which is a separate step from importing, puts new files on the computer, so only install from a source you trust, and only when you actually need that module.
Edge cases to watch for: first, importing by name fails when the module is not in the module path, even if the file exists somewhere else on disk. Import by path in that case. Second, a manifest with FunctionsToExport set to an empty list exports no functions, so the module will load but offer nothing to call, which looks like a broken import until you check the manifest. Third, a function name that breaks the Verb-Noun pattern can still work, but it may trigger a naming warning, and it is harder for others to guess. Keep public names in Verb-Noun form, with an approved style verb, so your tools are easy to find and easy to trust.
Worked examples
Read each example in order. Each one explains its parts, then shows what to look for in the output.
Syntax
Import-Module <ModuleName>Example 1
Import first, then use the module commands. The import lasts only for this session. The result limit of five keeps this read only query small.
Import-Module ActiveDirectory
Get-ADUser -Filter * -ResultSetSize 5 | Select-Object NameIllustrative output: Name ---- Izaz
Example 2
A one function module file. This text defines the function, it does not run it yet. Save it as MyTools.psm1, import it by path, then call Get-Greeting like any command.
# MyTools.psm1
function Get-Greeting {
param([string]$Name)
"Hello, $Name"
}Illustrative output: (no output shown, the file only defines the function until it is imported and called)
Example 3
Imports your own file by path, then calls its function with a small test name. Change the name and only the greeting should change.
Import-Module .\MyTools.psm1
Get-Greeting -Name IzazIllustrative output: Hello, Izaz
Example 4
Import-Module ActiveDirectory loads the directory commands into your current session. Get-Module ActiveDirectory then asks for that loaded module by name, so you can confirm the import worked. The output shows the module name and version, which is a quick check before you use its commands.
Import-Module ActiveDirectory
Get-Module ActiveDirectoryIllustrative output: Name Version ---- ------- ActiveDirectory 1.0.0.0
Example 5
PassThru makes a successful import return the module object, so you get a short confirmation line instead of silence.
Import-Module Microsoft.PowerShell.Management -PassThru | Select-Object Name, VersionIllustrative output: Name Version ---- ------- Microsoft.PowerShell.Management 3.1.0.0
Example 6
Reloads your edited module in the same session. Use this after you save a change to the .psm1 file, or the session keeps the old copy.
Import-Module .\MyTools.psm1 -ForceIllustrative output: (no output shown, which is normal for a successful import)
Example 7
Two functions in one file, but only Get-Greeting is exported. The helper stays private inside the module.
# MyTools.psm1
function Format-GreetingText {
param([string]$Name)
"Hello, $Name"
}
function Get-Greeting {
param([string]$Name)
Format-GreetingText -Name $Name
}
Export-ModuleMember -Function Get-GreetingIllustrative output: Hello, Izaz
Example 8
Warning: this writes a new manifest file on disk, so check the path first. It links the .psm1 file, sets the version, and lists the public function.
New-ModuleManifest -Path .\MyTools.psd1 -RootModule MyTools.psm1 -ModuleVersion 1.0.0 -Author "Your Name" -Description "Small greeting tools." -FunctionsToExport Get-GreetingIllustrative output: (no output shown, which is normal. Check the new .psd1 file, or validate it with Test-ModuleManifest.)
Example 9
Lists the commands your imported module actually offers, so you can check that only the public function appears.
Get-Command -Module MyTools | Select-Object Name, CommandTypeIllustrative output: Name CommandType ---- ----------- Get-Greeting Function
Example 10
Unloads the module from this session only. It does not delete the .psm1 file and does not uninstall anything. Import again to use it.
Remove-Module MyToolsIllustrative output: (no output shown, which is normal for a successful removal)
Nothing on this page executes PowerShell code. The outputs above are illustrative only.
Common mistakes and troubleshooting
Read these before you try the examples, so you can spot the same problems in your own work.
- Importing a module inside a script without checking it exists on the target computer. The script then fails far from home.
- Forgetting that an import lasts only for the current session. Reopen PowerShell and the commands are gone until you import again.
- Editing a .psm1 file after you imported it, and expecting the session you already have open to pick up the changes at once. A loaded module stays as it was when you imported it, so you need to import it again with -Force to load the new version.
- Mistaking silence after Import-Module for failure. A successful import shows no output by default. Confirm with -PassThru or with Get-Module, instead of importing again and again.
- Importing by name when the module file is outside the module path. Import by full path in that case, or move the module into a module path folder with a matching folder and file name.
- Importing a module from a source you do not trust. Importing runs module code in your session, so only import modules from sources you trust.
- Exporting every helper function, so the public surface grows and callers start depending on helpers you meant to keep private. Export only the functions others should use.
- Writing a manifest whose FunctionsToExport list does not match the .psm1 file. If the list is empty, the module loads but offers nothing to call. If a name is misspelled, that function will not be exported as expected.
- Building one giant module for every job, instead of small modules with one clear area each. A giant module is harder to test, harder to reuse, and harder to trust.
- Forgetting to test a custom module with a small, safe input after import. Test one public function first, before you use the module in a larger script.
Knowledge check
Knowledge check
What file holds the functions of a custom module?
Pick one answer. Feedback appears right away, and you can try again.
Remember this and next step
Remember this: import loads for this session only, a .psm1 file holds your functions, and a .psd1 manifest describes the module. Silence after a successful import is normal, so confirm with -PassThru or with Get-Module. Editing a loaded module needs a -Force reload. Removing a module only clears the session, it never deletes the files. Small, focused modules, with only their public functions exported, are easier to reuse, easier to test, and easier to trust.
Next step: Providers and drives