Importing Modules

To import modules, use the Import-Module cmdlet. When this cmdlet is run, Windows PowerShell searches for the specified module within the directories specified in the PSModulePath variable. When the specified directory is found, Windows PowerShell searches for files in the following order: module manifest files (.psd1), script module files (.psm1), binary module files (.dll). For more information about adding directories to the search, see PSModulePath Environment Variable.

Beginning in Windows PowerShell 3.0, modules are imported automatically when any cmdlet or function in the module is used in a command. This feature works on any module in a directory that this included in the value of the PSModulePath environment variable.

The following actions trigger automatic importing of a module, also known as "module auto-loading."

  • Using a cmdlet in a command. For example, typing Get-ExecutionPolicy imports the Microsoft.PowerShell.Security module that contains the Get-ExecutionPolicy cmdlet.

  • Using the Get-Command cmdlet to get the command. For example, typing Get-Command Get-JobTrigger imports the PSScheduledJob module that contains the Get-JobTrigger cmdlet. A Get-Command command that includes wildcard characters is considered to be discovery and does not trigger importing of a module.

  • Using the Get-Help cmdlet to get help for a cmdlet. For example, typing Get-Help Get-WinEvent imports the Microsoft.PowerShell.Diagnostics module that contains the Get-WinEvent cmdlet.

To support automatic importing of modules, the Get-Command cmdlet gets all cmdlets and functions in all installed modules, even if the module is not imported into the session. For more information, see the help topic for the Get-Command cmdlet.

The Importing Process

When a module is imported, a new session state is created for the module, and a PSModuleInfo object is created in memory. A session-state is created for each module that is imported (this includes the root module and any nested modules). The members that are exported from the root module, including any members that were exported to the root module by any nested modules, are then imported into the caller’s session state.

The metadata of members that are exported from a module have a ModuleName property. This property is populated with the name of the module that exported them.

Warning Caution:
If the name of an exported member uses an unapproved verb or if the name of the member uses restricted characters, a warning is displayed when the Import-Module cmdlet is run.

By default, the Import-Module cmdlet does not return any objects to the pipeline. However, the cmdlet supports a PassThru parameter that can be used to return a PSModuleInfo object for each module that is imported. To send output to the host, users should run the Write-Host cmdlet.

Restricting the Members That Are Imported

When a module is imported by using the Import-Module cmdlet, by default, all exported module members are imported into the session, including any commands exported to the module by a nested module. By default, variables and aliases are not exported. To restrict the members that are exported, use a module manifest. To restrict the members that are imported, use the following parameters of the Import-Module cmdlet.

  • Function: This parameter restricts the functions that are exported. (If you are using a module manifest, see the FunctionsToExport key.)

  • Cmdlet: This parameter restricts the cmdlets that are exported (If you are using a module manifest, see the CmdletsToExport key.)

  • Variable: This parameter restricts the variables that are exported (If you are using a module manifest, see the VariablesToExport key.)

  • Alias: This parameter restricts the aliases that are exported (If you are using a module manifest, see the AliasesToExport key.)

See Also

© 2014 Microsoft