powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Import-Module



NAME
Import-Module

SYNOPSIS
Adds modules to the current session.

SYNTAX
Import-Module [-Name] [-Alias ] [-ArgumentList ] [-AsCustomObject] [-Cmdlet ]>] [-Force] [-Function ] [-Global] [-PassThru] [-Prefix ] [-Variable ] [-Version ion>] []

Import-Module [-Assembly] [-Alias ] [-ArgumentList ] [-AsCustomObject] [-Cmdlet tring[]>] [-Force] [-Function ] [-Global] [-PassThru] [-Prefix ] [-Variable ] [-Version
] []

Import-Module [-ModuleInfo] [-Alias ] [-ArgumentList ] [-AsCustomObject] [-Cmd
let ] [-Force] [-Function ] [-Global] [-PassThru] [-Prefix ] [-Variable ] [-V
ersion ] []


DESCRIPTION
The Import-Module cmdlet adds one or more modules to the current session.

A module is a package that contains members (such as cmdlets, providers, scripts, functions, variables, and other t
ools and files) that can be used in Windows PowerShell. After a module is imported, you can use the module members
in your session.

To import a module, use the Name, Assembly, or ModuleInfo parameter to identify the module to import. By default, I
mport-Module imports all members that the module exports, but you can use the Alias, Function, Cmdlet, and Variable
parameters to restrict the members that are imported.

Import-Module imports a module only into the current session. To import the module into all sessions, add an Import
-Module command to your Windows PowerShell profile. For more information about profiles, see about_Profiles.

For more information about modules, see about_Modules.


PARAMETERS
-Alias
Imports only the specified aliases from the module into the current session. Enter a comma-separated list of al
iases. Wildcard characters are permitted.

Some modules automatically export selected aliases into your session when you import the module. This parameter
lets you select from among the exported aliases.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? true

-ArgumentList
Specifies arguments (parameter values) that are passed to a script module during the Import-Module command. Th
is parameter is valid only when you are importing a script module.

You can also refer to ArgumentList by its alias, "args". For more information, see about_Aliases.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-AsCustomObject []
Returns a custom object with members that represent the imported module members. This parameter is valid only f
or script modules.

When you use the AsCustomObject parameter, Import-Module imports the module members into the session and then r
eturns a PSCustomObject object instead of a PSModuleInfo object. You can save the custom object in a variable a
nd use dot notation to invoke the members.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Assembly
Imports the cmdlets and providers implemented in the specified assembly objects. Enter a variable that contains
assembly objects or a command that creates assembly objects. You can also pipe an assembly object to Import-Mo
dule.

When you use this parameter, only the cmdlets and providers implemented by the specified assemblies are importe
d. If the module contains other files, they are not imported, and you might be missing important members of the
module. Use this parameter for debugging and testing the module, or when you are instructed to use it by the m
odule author.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false

-Cmdlet
Imports only the specified cmdlets from the module into the current session. Enter a list of cmdlets. Wildcard
characters are permitted.

Some modules automatically export selected cmdlets into your session when you import the module. This parameter
lets you select from among the exported cmdlets.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? true

-Force []
Re-imports a module and its members, even if the module or its members have an access mode of read-only.

Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false

-Function
Imports only the specified functions from the module into the current session. Enter a list of functions. Wildc
ard characters are permitted.

Some modules automatically export selected functions into your session when you import the module. This paramet
er lets you select from among the exported functions.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? true

-Global []
When used in a script module (.psm1), this parameter imports modules into the global session state.

This parameter is effective only when it appears in a script module. Otherwise, it is ignored.

By default, the commands in a script module, including commands from nested modules, are imported into the call
er's session state. To restrict the commands that a module exports, use an Export-ModuleMember command in the s
cript module.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ModuleInfo
Specifies module objects to import. Enter a variable that contains the module objects, or a command that gets t
he module objects, such as a "get-module -listavailable" command. You can also pipe module objects to Import-Mo
dule.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false

-Name
Specifies the names of the modules to import. Enter the name of the module or the name of a file in the module,
such as a .psd1, .psm1, .dll, or ps1 file. File paths are optional. Wildcards are not permitted. You can also
pipe module names and file names to Import-Module.

If you omit a path, Import-Module looks for the module in the paths saved in the PSModulePath environment varia
ble ($env:PSModulePath).

Specify only the module name whenever possible. When you specify a file name, only the members that are impleme
nted in that file are imported. If the module contains other files, they are not imported, and you might be mis
sing important members of the module.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false

-PassThru []
Returns objects that represent the modules that were imported. By default, this cmdlet does not generate any ou
tput.

Notes
-- When you pipe the output of a "get-module -listavailable" command to an Import-Module command with the PassT
hru parameter, Import-Module returns the object that Get-Module passed to it without updating the object. As a
result, the Exported and NestedModules properties are not yet populated.

-- When you use the Prefix parameter to specify a prefix for the member, the prefix does not appear in the memb
er names in the properties of the module object. The object records what was exported before the prefix was app
lied.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Prefix
Adds the specified prefix to the nouns in the names of imported module members.

Use this parameter to avoid name conflicts that might occur when different members in the session have the same
name. This parameter does not change the module, and it does not affect files that the module imports for its
own use (known as "nested modules"). It affects only the names of members in the current session.

For example, if you specify the prefix "UTC" and then import a Get-Date cmdlet, the cmdlet is known in the sess
ion as Get-UTCDate, and it is not confused with the original Get-Date cmdlet.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Variable
Imports only the specified variables from the module into the current session. Enter a list of variables. Wildc
ard characters are permitted.

Some modules automatically export selected variables into your session when you import the module. This paramet
er lets you select from among the exported variables.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? true

-Version
Specifies the version of the module to import. Use this parameter when you have different versions of the same
module on your system.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
System.String, System.Management.Automation.PSModuleInfo, System.Reflection.Assembly
You can pipe a module name, module object, or assembly object to Import-Module.


OUTPUTS
None, System.Management.Automation.PSModuleInfo, or System.Management.Automation.PSCustomObject
By default, Import-Module does not generate any output. If you use the PassThru parameter, it generates a Syste
m.Management.Automation.PSModuleInfo object that represents the module. If you use the AsCustomObject parameter
, it generates a PSCustomObject object.


NOTES


You can also refer to Import-Module by its alias, "ipmo". For more information, see about_Aliases.

Before you can import a module, the module directory must be copied to a directory that is accessible to your l
ocal computer. For more information, see about_Modules.

Module members run in their own private module session state, so the commands that they use for internal proces
sing do not affect your session state.

If you import members with the same name and the same type into your session, Windows PowerShell uses the membe
r imported last by default. Variables and aliases are replaced, and the originals are not accessible. Functions
, cmdlets and providers are merely "shadowed" by the new members, and they can be accessed by qualifying the co
mmand name with the name of its snap-in, module, or function path.

To update the formatting data for commands that have been imported from a module, use the Update-FormatData cmd
let. Update-FormatData also updates the formatting data for commands in the session that were imported from mod
ules. If the formatting file for a module changes, you can run an Update-FormatData command to update the forma
tting data for imported commands. You do not need to import the module again.

To import a module that is created by Import-PSSession or Export-PSSession, the execution policy in the current
session cannot be Restricted or AllSigned, because the modules that Import-PSSession and Export-PSSession crea
te contains unsigned script files that are prohibited by these policies. To use Import-Module without changing
the execution policy for the local computer, use the Scope parameter of Set-ExecutionPolicy to set a less restr
ictive execution policy for a single process.


-------------------------- EXAMPLE 1 --------------------------

C:\PS>import-module -name BitsTransfer


Description
-----------
This command imports the members of the BitsTransfer module into the current session.

The Name parameter name (-Name) is optional and can be omitted.

By default, Import-Module does not generate any output when it imports a module. To request output, use the PassThr
u or AsCustomObject parameter, or the Verbose common parameter.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>get-module -listAvailable | import-module


Description
-----------
This command imports all available modules in the path specified by the PSModulePath environment variable ($env:psm
odulepath) into the current session.





-------------------------- EXAMPLE 3 --------------------------

C:\PS>$m = get-module -ListAvailable BitsTransfer, ServerBackup

C:\PS> import-module -moduleInfo $m


Description
-----------
These commands import the members of the BitsTransfer and ServerBackup modules into the current session.

The first command uses the Get-Module cmdlet to get PSModuleInfo objects that represent the BitsTransfer and Server
Backup modules. It saves the objects in the $m variable. The ListAvailable parameter is required when you are getti
ng modules that are not yet imported into the session.

The second command uses the ModuleInfo parameter of Import-Module to import the modules into the current session.

These commands are equivalent to using a pipeline operator (|) to send the output of a Get-Module command to Import
-Module.





-------------------------- EXAMPLE 4 --------------------------

C:\PS>import-module -name c:\ps-test\modules\test -verbose

VERBOSE: Loading module from path 'C:\ps-test\modules\Test\Test.psm1'.
VERBOSE: Exporting function 'my-parm'.
VERBOSE: Exporting function 'get-parm'.
VERBOSE: Exporting function 'get-spec'.
VERBOSE: Exporting function 'get-specDetails'.


Description
-----------
This command uses an explicit path to identify the module to import.

It also uses the Verbose common parameter to get a list of the items imported from the module. Without the Verbose,
PassThru, or AsCustomObject parameter, Import-Module does not generate any output when it imports a module.





-------------------------- EXAMPLE 5 --------------------------

C:\PS>import-module BitsTransfer -cmdlet Add-BitsTransferFile, Get-BitsTransfer

C:\PS> get-module BitsTransfer

Name : BitsTransfer
Path : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer\BitsTransfer.psd1
Description :
Guid : 8fa5064b-8479-4c5c-86ea-0d311fe48875
Version : 1.0.0.0
ModuleBase : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer
ModuleType : Manifest
PrivateData :
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {[Add-BitsTransfer, Add-BitsTransfer], [Complete-BitsTransfer, Complete-BitsTransfer], [Get-Bit
sTransfer, Get-BitsTransfer], [Rem
ove-BitsTransfer, Remove-BitsTransfer]...}
ExportedFunctions : {}
ExportedVariables : {}
NestedModules : {Microsoft.BackgroundIntelligentTransfer.Management}


C:\PS> get-command -module BitsTransfer

CommandType Name Definition
----------- ---- ----------
Cmdlet Add-BitsTransfer Add-BitsTransfer [-BitsJob] [-Source] [[-Destination] g[]>] [-Verbose] [-Debug] [-ErrorA...
Cmdlet Get-BitsTransfer Get-BitsTransfer [[-Name] ] [-AllUsers] [-Verbose] [-Debug] [-ErrorAction
] [-WarningActi...


Description
-----------
This example shows how to restrict the module members that are imported into the session and the effect of this com
mand on the session.

The first command imports only the Add-BitsTransfer and Get-BitsTransfer cmdlets from the BitsTransfer module. The
command uses the Cmdlet parameter to restrict the cmdlets that the module imports. You can also use the Alias, Vari
able, and Function parameters to restrict other members that a module imports.

The second command uses the Get-Module cmdlet to get the object that represents the BitsTransfer module. The Export
edCmdlets property lists all of the cmdlets that the module exports, even when they were not all imported.

The third command uses the Module parameter of the Get-Command cmdlet to get the commands that were imported from t
he BitsTransfer module. The results confirm that only the Add-BitsTransfer and Get-BitsTransfer cmdlets were import
ed.





-------------------------- EXAMPLE 6 --------------------------

C:\PS>import-module BitsTransfer -prefix PS -passthru

Name : bitstransfer
Path : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\bitstransfer\bitstransfer.psd1
Description :
Guid : 8fa5064b-8479-4c5c-86ea-0d311fe48875
Version : 1.0.0.0
ModuleBase : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\bitstransfer
ModuleType : Manifest
PrivateData :
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {[Add-BitsTransfer, Add-BitsTransfer], [Remove-BitsTransfer, Remove-BitsTransfer], [Complete-Bi
tsTransfer, Complete-BitsTransfer]
, [Get-BitsTransfer, Get-BitsTransfer]...}
ExportedFunctions : {}
ExportedVariables : {}
NestedModules : {Microsoft.BackgroundIntelligentTransfer.Management}


C:\PS> get-command -module bitstransfer

CommandType Name Definition
----------- ---- ----------
Cmdlet Add-PSBitsTransfer Add-PSBitsTransfer [-BitsJob] [-Source] ...
Cmdlet Complete-PSBitsTransfer Complete-PSBitsTransfer [-BitsJob] [-Verbose] [-Deb...
Cmdlet Get-PSBitsTransfer Get-PSBitsTransfer [[-Name] ] [-AllUsers] [-Verbose] ...
Cmdlet Remove-PSBitsTransfer Remove-PSBitsTransfer [-BitsJob] [-Verbose] [-Debug...
Cmdlet Resume-PSBitsTransfer Resume-PSBitsTransfer [-BitsJob] [-Asynchronous] [-...
Cmdlet Set-PSBitsTransfer Set-PSBitsTransfer [-BitsJob] [-DisplayName Cmdlet Start-PSBitsTransfer Start-PSBitsTransfer [[-Source] ] [[-Destination] Cmdlet Suspend-PSBitsTransfer Suspend-PSBitsTransfer [-BitsJob] [-Verbose] [-Debu...


Description
-----------
These commands import the BitsTransfer module into the current session, add a prefix to the member names, and then
display the prefixed member names.

The first command uses the Import-Module cmdlet to import the BitsTransfer module. It uses the Prefix parameter to
add the PS prefix to all members that are imported from the module and the PassThru parameter to return a module ob
ject that represents the imported module.

The module object that the command returns has an ExportedCmdlets property that lists the exported members. The pre
fix does not appear in the cmdlet names, because it is applied after the members are exported (but before they are
imported).

The second command uses the Get-Command cmdlet to get the members that have been imported from the module. It uses
the Module parameter to specify the module. The output shows that the module members were correctly prefixed.

The prefix that you use applies only to the members in the current session. It does not change the module.





-------------------------- EXAMPLE 7 --------------------------

C:\PS>get-module -list | format-table -property name, moduletype -auto

Name ModuleType
---- ----------
Show-Calendar Script
BitsTransfer Manifest
PSDiagnostics Manifest
TestCmdlets Script

C:\PS> $a = import-module -name Show-Calendar -asCustomObject

C:\PS> $a | get-member


TypeName: System.Management.Automation.PSCustomObject

Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.Object obj)
GetHashCode Method int GetHashCode()
GetType Method type GetType()
ToString Method string ToString()
Show-Calendar ScriptMethod System.Object Show-Calendar();

C:\PS> $a."show-calendar"()


Description
-----------
These commands demonstrate how to get and use the custom object that Import-Module returns.

Custom objects include synthetic members that represent each of the imported module members. For example, the cmdle
ts and functions in a module are converted to script methods of the custom object.

Custom objects are very useful in scripting. They are also useful when several imported objects have the same names
. Using the script method of an object is equivalent to specifying the fully qualified name of an imported member,
including its module name.

The AsCustomObject parameter can be used only with a script module, so the first task is to determine which of the
available modules is a script module.

The first command uses the Get-Module cmdlet to get the available modules. The command uses a pipeline operator (|)
to pass the module objects to the Format-Table cmdlet, which lists the Name and ModuleType of each module in a tab
le.

The second command uses the Import-Module cmdlet to import the Show-Calendar script module. The command uses the As
CustomObject parameter to request a custom object. The command saves the resulting custom object in the $a variable
.

The third command uses a pipeline operator to send the $a variable to the Get-Member cmdlet, which gets the propert
ies and methods of the PSCustomObject in $a. The output shows a Show-Calendar script method.

The last command uses the Show-Calendar script method. The method name must be enclosed in quotation marks, because
it includes a hyphen.





-------------------------- EXAMPLE 8 --------------------------

C:\PS>import-module BitsTransfer

C:\PS> import-module BitsTransfer -force -prefix PS


Description
-----------
This example shows how to use the Force parameter of Import-Module when you are re-importing a module into the same
session.

The first command imports the BitsTransfer module. The second command imports the module again, this time using the
Prefix parameter.

The second command also includes the Force parameter, which removes the module and then imports it again. Without t
his parameter, the session would include two copies of each BitsTransfer cmdlet, one with the standard name and one
with the prefixed name.





-------------------------- EXAMPLE 9 --------------------------

C:\PS>get-date

Saturday, September 12, 2009 6:47:04 PM

C:\PS> import-module TestModule

C:\PS> get-date
09255

C:\PS> get-command get-date | format-table -property commandtype, name, pssnapin, module -auto

CommandType Name pssnapin Module
----------- ---- -------- ------
Function Get-Date TestModule
Cmdlet Get-Date Microsoft.PowerShell.Utility


C:\PS> Microsoft.PowerShell.Utility\get-date

Saturday, September 12, 2009 6:33:23 PM


Description
-----------
This example shows how to run commands that have been hidden by imported commands.

The first command run the Get-Date cmdlet that comes with Windows PowerShell. It returns a DateTime object with the
current date.

The second command imports the TestModule module. This module includes a function named Get-Date that returns the J
ulian date.

The third command runs the Get-Date command again. Because functions take precedence over cmdlets, the Get-Date fun
ction from the TestModule module ran, instead of the Get-Date cmdlet.

The fourth command shows that there are two Get-Date commands in the session, a function from the TestModule module
and a cmdlet from the Microsoft.PowerShell.Utility snap-in.

The fifth command runs the hidden cmdlet by qualifying the command name with the snap-in name.

For more information about command precedence in Windows PowerShell, see about_command_precedence.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=141553
Get-Module
New-Module
Remove-Module
Export-ModuleMember
about_Modules