Import-Module

Syntax

Import-Module
      [-Global]
      [-Prefix <String>]
      [-Name] <String[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-PassThru]
      [-AsCustomObject]
      [-MinimumVersion <Version>]
      [-MaximumVersion <String>]
      [-RequiredVersion <Version>]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>]
      [<CommonParameters>]

Import-Module
      [-Global]
      [-Prefix <String>]
      [-Name] <String[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-PassThru]
      [-AsCustomObject]
      [-MinimumVersion <Version>]
      [-MaximumVersion <String>]
      [-RequiredVersion <Version>]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>]
      -PSSession <PSSession>
      [<CommonParameters>]

Import-Module
      [-Global]
      [-Prefix <String>]
      [-Name] <String[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-PassThru]
      [-AsCustomObject]
      [-MinimumVersion <Version>]
      [-MaximumVersion <String>]
      [-RequiredVersion <Version>]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>]
      -CimSession <CimSession>
      [-CimResourceUri <Uri>]
      [-CimNamespace <String>]
      [<CommonParameters>]

Import-Module
      [-Global]
      [-Prefix <String>]
      [-FullyQualifiedName] <ModuleSpecification[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-PassThru]
      [-AsCustomObject]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>]
      [<CommonParameters>]

Import-Module
      [-Global]
      [-Prefix <String>]
      [-FullyQualifiedName] <ModuleSpecification[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-PassThru]
      [-AsCustomObject]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>]
      -PSSession <PSSession>
      [<CommonParameters>]

Import-Module
      [-Global]
      [-Prefix <String>]
      [-Assembly] <Assembly[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-PassThru]
      [-AsCustomObject]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>]
      [<CommonParameters>]

Import-Module
      [-Global]
      [-Prefix <String>]
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-PassThru]
      [-AsCustomObject]
      [-ModuleInfo] <PSModuleInfo[]>
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>]
      [<CommonParameters>]

Description

The Import-Module cmdlet adds one or more modules to the current session. The modules that you import must be installed on the local computer or a remote computer.

Starting in PowerShell 3.0, installed modules are automatically imported to the session when you use any commands or providers in the module. However, you can still use the Import-Module command to import a module and you can enable and disable automatic module importing by using the $PSModuleAutoloadingPreference preference variable. For more information about modules, see about_Modules. For more information about the $PSModuleAutoloadingPreference variable, see about_Preference_Variables.

A module is a package that contains members that can be used in PowerShell. Members include cmdlets, providers, scripts, functions, variables, and other tools and files. After a module is imported, you can use the module members in your session.

To import a module, use the Name, Assembly, ModuleInfo, MinimumVersion and RequiredVersion parameters to identify the module to import. By default, Import-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. You can also use the NoClobber parameter to prevent Import-Module from importing members that have the same names as members in the current session.

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

Starting in Windows PowerShell 3.0, you can use Import-Module to import Common Information Model (CIM) modules, in which the cmdlets are defined in Cmdlet Definition XML (CDXML) files. This feature allows you to use cmdlets that are implemented in non-managed code assemblies, such as those written in C++.

With these new features, Import-Module cmdlet becomes a primary tool for managing heterogeneous enterprises that include computers that run the Windows operating system and computers that are running other operating systems.

To manage remote computers that run the Windows operating system that have PowerShell and PowerShell remoting enabled, create a PSSession on the remote computer and then use the PSSession parameter of Get-Module to get the PowerShell modules in the PSSession. When you import the modules, and then use the imported commands in the current session, the commands run implicitly in the PSSession on the remote computer. You can use this strategy to manage the remote computer.

You can use a similar strategy to manage computers that don't have PowerShell remoting enabled, including computers that are not running the Windows operating system, and Windows computers that have PowerShell, but don't have PowerShell remoting enabled.

Start by creating a CIM session on the remote computer, which is a connection to Windows Management Instrumentation (WMI) on the remote computer. Then use the CIMSession parameter of Import-Module to import CIM modules from the remote computer. When you import a CIM module and then run the imported commands, the commands run implicitly on the remote computer. You can use this WMI and CIM strategy to manage the remote computer.

Examples

Example 1: Import the members of a module into the current session

This example imports the members of the PSDiagnostics module into the current session. The Name parameter name is optional and can be omitted.

Import-Module -Name PSDiagnostics

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

Example 2: Import all modules specified by the module path

This example imports all available modules in the path specified by the $env:PSModulePath environment variable into the current session.

Get-Module -ListAvailable | Import-Module

Example 3: Import the members of several modules into the current session

This example imports the members of the PSDiagnostics and Dism modules into the current session.

$m = Get-Module -ListAvailable PSDiagnostics, Dism
Import-Module -ModuleInfo $m

The Get-Module cmdlet gets the PSDiagnostics and Dism modules and saves the objects in the $m variable. The ListAvailable parameter is required when you are getting modules that are not yet imported into the session.

The ModuleInfo parameter of Import-Module is used 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: Import all modules specified by a path

This example uses an explicit path to identify the module to import.

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-Parameter'.
VERBOSE: Exporting function 'Get-Specification'.
VERBOSE: Exporting function 'Get-SpecDetails'.

Using the Verbose parameter causes Import-Module to report progress as it loads the module. Without the Verbose, PassThru, or AsCustomObject parameter, Import-Module does not generate any output when it imports a module.

Example 5: Restrict module members imported into a session

This example shows how to restrict which module members are imported into the session and the effect of this command on the session.

Import-Module PSDiagnostics -Function Disable-PSTrace, Enable-PSTrace
(Get-Module PSDiagnostics).ExportedCommands

Key                          Value
---                          -----
Disable-PSTrace              Disable-PSTrace
Disable-PSWSManCombinedTrace Disable-PSWSManCombinedTrace
Disable-WSManTrace           Disable-WSManTrace
Enable-PSTrace               Enable-PSTrace
Enable-PSWSManCombinedTrace  Enable-PSWSManCombinedTrace
Enable-WSManTrace            Enable-WSManTrace
Get-LogProperties            Get-LogProperties
Set-LogProperties            Set-LogProperties
Start-Trace                  Start-Trace
Stop-Trace                   Stop-Trace

Get-Command -Module PSDiagnostics

CommandType     Name                 Version    Source
-----------     ----                 -------    ------
Function        Disable-PSTrace      6.1.0.0    PSDiagnostics
Function        Enable-PSTrace       6.1.0.0    PSDiagnostics

The first command imports only the Disable-PSTrace and Enable-PSTrace cmdlets from the PSDiagnostics module. The Function parameter limits the members that are imported from the module. You can also use the Alias, Variable, and Cmdlet parameters to restrict other members that a module imports.

The Get-Module cmdlet gets the object that represents the PSDiagnostics module. The ExportedCmdlets property lists all the cmdlets that the module exports, even though they were not all imported.

In the third command, the Module parameter of the Get-Command cmdlet gets the commands that were imported from the PSDiagnostics module. The results confirm that only the Disable-PSTrace and Enable-PSTrace cmdlets were imported.

Example 6: Import the members of a module and add a prefix

This example imports the PSDiagnostics module into the current session, adds a prefix to the member names, and then displays the prefixed member names. The prefix applies only to the members in the current session. It does not change the module.

Import-Module PSDiagnostics -Prefix x -PassThru

ModuleType Version    Name               ExportedCommands
---------- -------    ----               ----------------
Script     6.1.0.0    PSDiagnostics      {Disable-xPSTrace, Disable-xPSWSManCombinedTrace, Disable-xW...

Get-Command -Module PSDiagnostics

CommandType     Name                                   Version    Source
-----------     ----                                   -------    ------
Function        Disable-xPSTrace                       6.1.0.0    PSDiagnostics
Function        Disable-xPSWSManCombinedTrace          6.1.0.0    PSDiagnostics
Function        Disable-xWSManTrace                    6.1.0.0    PSDiagnostics
Function        Enable-xPSTrace                        6.1.0.0    PSDiagnostics
Function        Enable-xPSWSManCombinedTrace           6.1.0.0    PSDiagnostics
Function        Enable-xWSManTrace                     6.1.0.0    PSDiagnostics
Function        Get-xLogProperties                     6.1.0.0    PSDiagnostics
Function        Set-xLogProperties                     6.1.0.0    PSDiagnostics
Function        Start-xTrace                           6.1.0.0    PSDiagnostics
Function        Stop-xTrace                            6.1.0.0    PSDiagnostics

It uses the Prefix parameter of Import-Module adds the x prefix to all members that are imported from the module and the PassThru parameter to return a module object that represents the imported module.

The Get-Command cmdlet to get the members that have been imported from the module. The output shows that the module members were correctly prefixed.

Example 7: Get and use a custom object

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 cmdlets 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 when importing a script module, so the first task is to determine which of the available modules is a script module.

Get-Module -List | Format-Table -Property Name, ModuleType -AutoSize

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

$a = Import-Module -Name Show-Calendar -AsCustomObject -Passthru
$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();

$a."Show-Calendar"()

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 table.

The second command uses the Import-Module cmdlet to import the Show-Calendar script module. The command uses the AsCustomObject parameter to request a custom object and the PassThru parameter to return the 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 properties 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: Re-import a module into the same session

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

Import-Module PSDiagnostics
Import-Module PSDiagnostics -Force -Prefix PS

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

Using the Force parameter, Import-Module removes the module and then imports it again. Without this parameter, the session would include two copies of each PSDiagnostics cmdlet, one with the standard name and one with the prefixed name.

Example 9: Run commands that have been hidden by imported commands

This example shows how to run commands that have been hidden by imported commands. The TestModule module. includes a function named Get-Date that returns the year and day of the year.

Get-Date

Thursday, August 15, 2019 2:26:12 PM

Import-Module TestModule
Get-Date

19227

Get-Command Get-Date -All | Format-Table -Property CommandType, Name, ModuleName -AutoSize

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

Microsoft.PowerShell.Utility\Get-Date

Thursday, August 15, 2019 2:26:12 PM

The first Get-Datecmdlet returns a **DateTime** object with the current date. After importing the **TestModule** module,Get-Date` returns the year and day of the year.

Using the All parameter of the Get-Command we get all of the Get-Date commands in the session. The results show that there are two Get-Date commands in the session, a function from the TestModule module and a cmdlet from the Microsoft.PowerShell.Utility module.

Because functions take precedence over cmdlets, the Get-Date function from the TestModule module runs, instead of the Get-Date cmdlet. To run the original version of Get-Date you must qualify the command name with the module name.

For more information about command precedence in PowerShell, see about_Command_Precedence.

Example 10: Import a minimum version of a module

Import-Module -Name PSWorkflow -MinimumVersion 3.0.0.0

This command imports the PSWorkflow module. It uses the MinimumVersion parameter of Import-Module to import only version 3.0.0.0 or greater of the module.

You can also use the RequiredVersion parameter to import a particular version of a module, or use the Module and Version parameters of the #Requires keyword to require a particular version of a module in a script.

Example 11: Import a module from a remote computer

This example shows how to use the Import-Module cmdlet to import a module from a remote computer. This command uses the Implicit Remoting feature of PowerShell.

When you import modules from another session, you can use the cmdlets in the current session. However, commands that use the cmdlets actually run in the remote session.

$s = New-PSSession -ComputerName Server01
Get-Module -PSSession $s -ListAvailable -Name NetSecurity

ModuleType Name                                ExportedCommands
---------- ----                                ----------------
Manifest   NetSecurity                         {New-NetIPsecAuthProposal, New-NetIPsecMainModeCryptoProposal, New-Ne...

Import-Module -PSSession $s -Name NetSecurity
Get-Command -Module NetSecurity -Name Get-*Firewall*

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Function        Get-NetFirewallAddressFilter                       NetSecurity
Function        Get-NetFirewallApplicationFilter                   NetSecurity
Function        Get-NetFirewallInterfaceFilter                     NetSecurity
Function        Get-NetFirewallInterfaceTypeFilter                 NetSecurity
Function        Get-NetFirewallPortFilter                          NetSecurity
Function        Get-NetFirewallProfile                             NetSecurity
Function        Get-NetFirewallRule                                NetSecurity
Function        Get-NetFirewallSecurityFilter                      NetSecurity
Function        Get-NetFirewallServiceFilter                       NetSecurity
Function        Get-NetFirewallSetting                             NetSecurity

Get-NetFirewallRule -DisplayName "Windows Remote Management*" | Format-Table -Property DisplayName, Name -AutoSize

DisplayName                                              Name
-----------                                              ----
Windows Remote Management (HTTP-In)                      WINRM-HTTP-In-TCP
Windows Remote Management (HTTP-In)                      WINRM-HTTP-In-TCP-PUBLIC
Windows Remote Management - Compatibility Mode (HTTP-In) WINRM-HTTP-Compat-In-TCP

The first command uses the New-PSSession cmdlet to create a remote session (PSSession) to the Server01 computer. The command saves the PSSession in the $s variable.

The second command uses the PSSession parameter of the Get-Module cmdlet to get the NetSecurity module in the session in the $s variable. This command is equivalent to using the Invoke-Command cmdlet to run a Get-Module command in the session in $s (Invoke-Command $s {Get-Module -ListAvailable -Name NetSecurity).The output shows that the NetSecurity module is installed on the computer and is available to the session in the $s variable.

The third command uses the PSSession parameter of the Import-Module cmdlet to import the NetSecurity module from the session in the $s variable into the current session.

The fourth command uses the Get-Command cmdlet to get commands that begin with Get and include Firewall from the NetSecurity module.The output gets the commands and confirms that the module and its cmdlets were imported into the current session.

The fifth command uses the Get-NetFirewallRule cmdlet to get Windows Remote Management firewall rules on the Server01 computer. This command is equivalent to using the Invoke-Command cmdlet to run a Get-NetFirewallRule command on the session in the $s variable.

Example 12: Manage storage on a remote computer without the Windows operating system

In this example, because the administrator of the computer has installed the Module Discovery WMI provider, the CIM commands can use the default values, which are designed for the provider.

The commands in this example enable you to manage the storage systems of a remote computer that is not running the Windows operating system.

The first command uses the New-CimSession cmdlet to create a session on the RSDGF03 remote computer. The session connects to WMI on the remote computer. The command saves the CIM session in the $cs variable.

The second command uses the CIM session in the $cs variable to run an Import-Module command on the RSDGF03 computer. The command uses the Name parameter to specify the Storage CIM module.

The third command runs the Get-Command command on the Get-Disk command in the Storage module. When you import a CIM module into the local session, PowerShell converts the CDXML files for each command into PowerShell scripts, which appear as functions in the local session.

The fourth command runs the Get-Disk command. Although the command is typed in the local session, it runs implicitly on the remote computer from which it was imported.The command gets objects from the remote computer and returns them to the local session.

$cs = New-CimSession -ComputerName RSDGF03
Import-Module -CimSession $cs -Name Storage
# Importing a CIM module, converts the CDXML files for each command into PowerShell scripts.
# These appear as functions in the local session.
Get-Command Get-Disk

CommandType     Name                  ModuleName
-----------     ----                  ----------
Function        Get-Disk              Storage

# Use implicit remoting to query disks on the remote computer from which the module was imported.
Get-Disk

Number Friendly Name              OperationalStatus          Total Size Partition Style
------ -------------              -----------------          ---------- ---------------
0      Virtual HD ATA Device      Online                          40 GB MBR

Parameters

-Alias

-ArgumentList

-AsCustomObject

-Assembly

-CimNamespace

-CimResourceUri

-CimSession

-Cmdlet

-DisableNameChecking

-Force

-FullyQualifiedName

-Function

-Global

-MaximumVersion

-MinimumVersion

-ModuleInfo

-Name

-NoClobber

-PassThru

-Prefix

-PSSession

-RequiredVersion

-Scope

-Variable

Inputs

System.String, System.Management.Automation.PSModuleInfo, System.Reflection.Assembly

You can pipe a module name, module object, or assembly object to this cmdlet.

Outputs

None, System.Management.Automation.PSModuleInfo, or System.Management.Automation.PSCustomObject

This cmdlet returns a PSModuleInfo or PSCustomObject. By default, Import-Module does not generate any output. If you specify the PassThru parameter, the cmdlet generates a System.Management.Automation.PSModuleInfo object that represents the module. If you specify the AsCustomObject parameter, it generates a PSCustomObject object.

Notes

• Before you can import a module, the module must be installed on the local computer. That is, the module directory must be copied to a directory that is accessible to your local computer. For more information, see about_Modules.

  You can also use the PSSession and CIMSession parameters to import modules that are installed on remote computers. However, commands that use the cmdlets in these modules actually run in the remote session on the remote computer.

• If you import members with the same name and the same type into your session, PowerShell uses the member 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. They can be accessed by qualifying the command 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 cmdlet. Update-FormatData also updates the formatting data for commands in the session that were imported from modules. If the formatting file for a module changes, you can run an Update-FormatData command to update the formatting data for imported commands. You don't need to import the module again.

• Starting in Windows PowerShell 3.0, the core commands that are installed with PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of PowerShell, the core commands are packaged in snap-ins (PSSnapins). The exception is Microsoft.PowerShell.Core, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins.

  For information about the CreateDefault2 method that creates newer-style sessions with core modules, see the CreateDefault2 Method.

• Import-Module cannot import PowerShell Core modules from another session. The PowerShell Core modules have names that begin with Microsoft.PowerShell.

• In Windows PowerShell 2.0, some of the property values of the module object, such as the ExportedCmdlets and NestedModules property values, were not populated until the module was imported and were not available on the module object that the PassThru parameter returns. In Windows PowerShell 3.0, all module property values are populated.

• If you attempt to import a module that contains mixed-mode assemblies that are not compatible with Windows PowerShell 3.0, Import-Module returns an error message like the following one.

  Import-Module : Mixed mode assembly is built against version 'v2.0.50727' of the runtime and cannot be loaded in the 4.0 runtime without additional configuration information.

  This error occurs when a module that is designed for Windows PowerShell 2.0 contains at least one mixed-module assembly, that is, an assembly that includes both managed and non-managed code, such as C++ and C#.

  To import a module that contains mixed-mode assemblies, start Windows PowerShell 2.0 by using the following command, and then try the Import-Module command again.

  PowerShell.exe -Version 2.0

• To use the CIM session feature, the remote computer must have WS-Management remoting and Windows Management Instrumentation (WMI), which is the Microsoft implementation of the Common Information Model (CIM) standard. The computer must also have the Module Discovery WMI provider or an alternate CIM provider that has the same basic features.

  You can use the CIM session feature on computers that are not running a Windows operating system and on Windows computers that have PowerShell, but don't have PowerShell remoting enabled.

  You can also use the CIM parameters to get CIM modules from computers that have PowerShell remoting enabled, including the local computer. When you create a CIM session on the local computer, PowerShell uses DCOM, instead of WMI, to create the session.

Related Links

• Export-ModuleMember
• Get-Module
• New-Module
• Remove-Module