Explains how to install, import, and use Windows PowerShell modules.
A module is a package that contains Windows PowerShell commands, such as
cmdlets, providers, functions, workflows, variables, and aliases.
People who write commands can use modules to organize their commands and
share them with others. People who receive modules can add the commands
in the modules to their Windows PowerShell sessions and use them just like
the built-in commands.
This topic explains how to use Windows PowerShell modules. For information
about how to write Windows PowerShell modules, see "Writing a Windows
PowerShell Module" in the MSDN (Microsoft Developer Network) library
WHAT IS A MODULE?
A module is a package of commands. All cmdlets and providers in your
session are added by a module or a snap-in.
WHAT'S NEW IN MODULES: Module Auto-Loading
Beginning in Windows PowerShell 3.0, Windows PowerShell imports
modules automatically the first time that you use any command in
an installed module. You can now use the commands in a module
without any set-up or profile configuration, so there's no need to
manage modules after you install them on your computer.
The commands in a module are also easier to find. The Get-Command cmdlet
now gets all commands in all installed modules, even if they are not yet
in the session, so you can find a command and use it without importing.
Any of the following commands will import a module into your session.
#Run the command
Get-Mailbox -Identity Chrisá
#Get the command
#Get help for the command
Get-Command commands that include a wildcard character (*) are considered
to be discovery, not use, and do not import any modules.
Only module that are stored in the location specified by the PSModulePath
environment variable are automatically imported. Modules in other locations
must be imported by using the Import-Module cmdlet.
Also, commands that use Windows PowerShell providers do not automatically
import a module. For example, if you use a command that requires the WSMan:
drive, such as the Get-PSSessionConfiguration cmdlet, you might need to
use the Import-Module cmdlet to import the Microsoft.WSMan.Management
module that includes the WSMan: drive.
You can still use the Import-Module command to import a module and
use the $PSModuleAutoloadingPreference variable to enable, disable and
configure automatic importing of modules. For more information, see
HOW TO USE A MODULE
To use a module, perform the following tasks:
1. Install the module. (This is often done for you.)
2. Find the commands that the module added.
3. Use the commands that the module added.
This topic explains how to perform these tasks. It also includes
other useful information about managing modules.
HOW TO INSTALL A MODULE
If you receive a module as a folder with files in it, you need
to install it on your computer before you can use it into Windows
Most modules are installed for you. Windows PowerShell comes with
several pre-installed modules. In Windows Server 2008 R2, the
Add Features Wizard in Server Manager automatically installs the
feature modules that you select. Many other modules come in an
installer or Setup program that installs the module.
To install a module folder:
1. Create a Modules directory for the current user if one does
To create a Modules directory, type:
New-Item -Type Directory -Path $home\Documents\WindowsPowerShell\Modules
2. Copy the entire module folder into the Modules directory.
You can use any method to copy the folder, including Windows
Explorer and Cmd.exe, as well as Windows PowerShell.
In Windows PowerShell use the Copy-Item cmdlet. For example, to copy the
MyModule folder from C:\ps-test\MyModule to the Modules directory, type:
Copy-Item -Path c:\ps-test\MyModule -Destination $home\Documents\WindowsPowerShell\Modules
You can install a module in any location, but installing your modules in a
default module location makes them easier to manage. For more information about
the default module locations, see the "Module Locations and PSModulePath" section.
HOW TO FIND INSTALLED MODULES
To find modules that are installed in a default module location,
but not yet imported into your session, type:
To find the modules that have already been imported into your session,
at the Windows PowerShell prompt, type:
For more information about the Get-Module cmdlet, see Get-Module.
HOW TO FIND THE COMMANDS IN A MODULE
Use the Get-Command cmdlet to find all available commands. You can use the
parameters of the Get-Command cmdlet to filter commands such as by
module, name, and noun.
To find all commands in a module, type:
For example, to find the commands in the BitsTransfer module, type:
Get-Command -Module BitsTransfer
For more information about the Get-Command cmdlet, see Get-Command.
HOW TO GET HELP FOR THE COMMANDS IN A MODULE
If the module contains Help files for the commands that it exports,
the Get-Help cmdlet will display the Help topics. Use the same Get-Help
command format that you would use to get help for any command in Windows
Beginning in Windows PowerShell 3.0, you can download Help files for
a module and download updates to the Help files so they are never
To get help for a commands in a module,
To get help online for command in a module, type:
To download and install the help files for the commands in a module,
For more information, see Get-Help and Update-Help.
HOW TO IMPORT A MODULE
You might have to import a module or import a module file. Importing is required
when a module is not installed in the locations specified by the PSModulePath
environment variable ($env:PSModulePath), or the module consists of file, such
as a .dll or .psm1 file, instead of typical module that is delivered as a folder.
You might also choose to import a module so that you can use the parameters of the
Import-Module command, such as the Prefix parameter, which adds a distinctive prefix
to the noun names of all imported commands, or the NoClobber parameter, which prevents
the module from adding commands that would hide or replace existing commands in the
To import modules, use the Import-Module cmdlet.
To import modules in a PSModulePath location into the current session, use the
following command format.
For example, the following command imports the BitsTransfer module
into the current session.
To import a module that is not in a default module location, use
the fully qualified path to the module folder in the command.
For example, to add the TestCmdlets module in the C:\ps-test directory
to your session, type:
To import a module file that is not contained in a module folder, use
the fully qualified path to the module file in the command.
For example, to add the TestCmdlets.dll module in the C:\ps-test directory
to your session, type:
For more information about adding modules to your session, see
HOW TO IMPORT A MODULE INTO EVERY SESSION
The Import-Module command imports modules into your current Windows
PowerShell session. This command affects only the current session.
To import a module into every Windows PowerShell session that you
start, add the Import-Module command to your Windows PowerShell
For more information about profiles, see about_Profiles.
HOW TO REMOVE A MODULE
When you remove a module, the commands that the module added are deleted
from the session.
To remove a module from your session, use the following command
For example, the following command removes the BitsTransfer module
from the current session.
Removing a module reverses the operation of importing a module. Removing
a module does not uninstall the module. For more information about the
Remove-Module cmdlet, see Remove-Module.
MODULE LOCATIONS AND PSMODULEPATH
There are two default locations for Windows PowerShell modules, one for
the system and one for the current user.
Current user: $home\Documents\WindowsPowerShell\Modules
- or -
Note: To add or change files in the %Windir%\System32 directory,
start Windows PowerShell with the "Run as administrator" option.
You can change the default module locations on your system by changing the
value of the PSModulePath environment variable ($Env:PSModulePath). The
PSModulePath environment variable is modeled on the Path environment variable
and has the same format.
To view the default module locations, type:
To add a default module location, use the following command format.
$env:psmodulepath = $env:psmodulepath + ";"
The semi-colon (;) in the command separates the new path from the
path that precedes it in the list.
For example, to add the "C:\ps-test\Modules" directory, type:
$env:psmodulepath + ";c:\ps-test\Modules"
When you add a path to PSModulePath, Get-Module and Import-Module
commands include modules in that path.
The value that you set affects only the current session. To make the
change persistent, add the command to your Windows PowerShell profile
or use System in Control Panel to change the value of the PSModulePath
environment variable in the registry.
Also, to make the change persistent, you can also use the
SetEnvironmentVariable method of the System.Environment class to add
a Path to the PSModulePath environment variable.
For more information about the PSModulePath variable, see
MODULES AND NAME CONFLICTS
Name conflicts occur when more than one command in the session
has the same name. Importing a module causes a name conflict when
commands in the module have the same names as commands or items
in the session.
Name conflicts can result in commands being hidden or replaced.
-- Hidden. A command is hidden when it is not the command
that runs when you type the command name, but you can run it
by using another method, such as by qualifying the command
name with the name of the module or snap-in in which it
-- Replaced. A command is replaced when you cannot run it because
it has been overwritten by a command with the same name. Even
when you remove the module that caused the conflict, you cannot
run a replaced command unless you restart the session.
Import-Module might add commands that hide and replace commands in the
current session. Also, commands in your session can hide commands that
the module added.
To detect name conflicts, use the All parameter of the Get-Command cmdlet.
Beginning in Windows PowerShell 3.0, Get-Command gets only that commands
that run when you type the command name. The All parameter gets all commands
with the specific name in the session.
To prevent name conflicts, use the NoClobber or Prefix parameters of
the Import-Module cmdlet. The Prefix parameter adds a prefix to the names
of imported commands so that they are unique in the session. The NoClobber
parameter does not import any commands that would hide or replace existing
commands in the session.
You can also use the Alias, Cmdlet, Function, and Variable parameters
of Import-Module to select only the commands that you want to import,
and you can exclude commands that cause name conflicts in your session.
Module authors can prevent name conflicts by using the DefaultCommandPrefix
property of the module manifest to add a default prefix to all command
names. The value of the Prefix parameter takes precedence over the value
Even if a command is hidden, you can run it by qualifying the command
name with the name of the module or snap-in in which it originated.
The Windows PowerShell command precedence rules determine which command
runs when the session includes commands with the same name.
For example, when a session includes a function and a cmdlet with the same
name, Windows PowerShell runs the function by default. When the session
includes commands of the same type with the same name, such as two cmdlets
with the same name, by default, it runs the most recently added command.
For more information, including an explanation of the precedence rules and
instructions for running hidden commands, see about_Command_Precedence.
MODULES AND SNAP-INS
You can add commands to your session from modules and snap-ins. Modules
can add all types of commands, including cmdlets, providers, and functions,
and items, such as variables, aliases, and Windows PowerShell drives.
Snap-ins can add only cmdlets and providers.
Before removing a module or snap-in from your session, use the following
commands to determine which commands will be removed.
To find the source of a cmdlet in your session, use the following command
get-command | format-list -property verb, noun, pssnapin, module
For example, to find the source of the Get-Date cmdlet, type:
get-command get-date | format-list -property verb, noun, pssnapin, module
For more information about Windows PowerShell snap-ins, see about_PSSnapins.
MODULE-RELATED WARNINGS AND ERRORS
The commands that a module exports should follow the Windows PowerShell
command naming rules. If the module that you import exports cmdlets or
functions that have unapproved verbs in their names, the Import-Module
cmdlet displays the following warning message.
WARNING: Some imported command names include unapproved verbs
which might make them less discoverable. Use the Verbose parameter
for more detail or type Get-Verb to see the list of approved verbs.
This message is only a warning. The complete module is still imported,
including the non-conforming commands. Although the message is displayed
to module users, the naming problem should be fixed by the module author.
To suppress the warning message, use the DisableNameChecking parameter
of the Import-Module cmdlet.
BUILT-IN MODULES AND SNAP-INS
In Windows PowerShell 2.0 and in older-style host programs in Windows
PowerShell 3.0 and later, the core commands that are installed with
Windows PowerShell are packaged in snap-ins that are added automatically
to every Windows PowerShell session.
Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that
implement the InitialSessionState.CreateDefault2 initial session state API --
the core commands are packaged in modules. The default is
Microsoft.PowerShell.Core, which is always a snap-in.
The Microsoft.PowerShell.Core snap-in is added to every session by
default. Modules are loaded automatically on first-use.
NOTE: Remote sessions, including sessions that are started by using
the New-PSSession cmdlet, are older-style sessions in which the built-in
commands are packaged in snap-ins.
The following modules (or snap-ins) are installed with Windows PowerShell.
LOGGING MODULE EVENTS
Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets
and functions in Windows PowerShell modules and snap-ins by setting the
LogPipelineExecutionDetails property of modules and snap-ins to $True. You can also
use a Group Policy setting, Turn on Module Logging, to enable module logging in
all Windows PowerShell sessions. For more information, see about_EventLogs
(http://go.microsoft.com/fwlink/?LinkID=113224) and about_Group_Policy_Settings