about_PowerShell_Config
Short description
Configuration files for PowerShell, replacing Registry configuration.
Long description
The powershell.config.json
file contains configuration settings for
PowerShell. PowerShell loads this configuration at startup. The settings can
also be modified at runtime. Previously, these settings were stored in the
Windows Registry for PowerShell, but are now contained in a file to enable
configuration on macOS and Linux.
Summary of settings
The powershell.config.json
file can contain the following keys:
DisableImplicitWinCompat
WindowsPowerShellCompatibilityModuleDenyList
WindowsPowerShellCompatibilityNoClobberModuleList
ExperimentalFeatures
LogChannels
LogIdentity
LogKeywords
LogLevel
Microsoft.PowerShell:ExecutionPolicy
PSModulePath
PowerShellPolicies
ExecutionPolicy
ConsoleSessionConfiguration
ModuleLogging
ProtectedEventLogging
ScriptBlockLogging
ScriptExecution
Transcription
UpdatableHelp
Not all keys apply to all platforms. The PowerShellPolicies
key contains
subkeys that mirror the settings managed by Window Group Policy. Those subkeys
also apply to all platforms when defined at the root level of the JSON file.
Warning
Unrecognized keys or invalid values in the configuration file are ignored. If
the powershell.config.json
file contains invalid JSON, PowerShell can't
start an interactive session. If this occurs, you must fix the configuration
file.
Configuration scope
Configuration settings can be defined for all users or at the individual user level.
AllUsers (shared) configuration
A powershell.config.json
file in the $PSHOME
directory defines the
configuration for all PowerShell sessions running from that PowerShell
installation.
Note
The $PSHOME
location is defined as the same directory as the executing
System.Management.Automation.dll assembly. This applies to hosted PowerShell
SDK instances as well.
CurrentUser (per-user) configurations
You can also configure PowerShell on a per-user basis by placing the file in
the user-scope configuration directory. The user configuration directory can be
found across platforms with the command
Split-Path $PROFILE.CurrentUserCurrentHost
.
Scope precedence
On Windows, settings managed by Windows Group Policy take precedence over settings in the configuration file. Group Policy doesn't exist on non-Windows platforms.
After Group Policy, settings defined at the AllUsers level take precedence over settings defined for the CurrentUser level.
Windows-specific settings
The following settings only apply to Windows platforms.
DisableImplicitWinCompat
WindowsPowerShellCompatibilityModuleDenyList
WindowsPowerShellCompatibilityNoClobberModuleList
ExecutionPolicy
PowerShellPolicies
DisableImplicitWinCompat
When set to true
, this setting disables the Windows PowerShell Compatibility
feature. Windows PowerShell Compatibility allows PowerShell 7 to load Windows
PowerShell 5.1 modules in compatibility mode.
For more information, see about_Windows_PowerShell_Compatibility.
WindowsPowerShellCompatibilityModuleDenyList
This setting is an array of module names that you want to exclude from participation in the Windows PowerShell Compatibility feature.
For more information, see about_Windows_PowerShell_Compatibility.
WindowsPowerShellCompatibilityNoClobberModuleList
This setting is an array of module names that shouldn't be clobbered by loading the Windows PowerShell 5.1 version of the module.
For more information, see about_Windows_PowerShell_Compatibility.
ExecutionPolicy
Important
This configuration only applies on Windows platforms.
Configures the execution policy for PowerShell sessions, determining what scripts can be run. By default, PowerShell uses the existing execution policy.
For AllUsers configurations, this sets the LocalMachine execution policy. For CurrentUser configurations, this sets the CurrentUser execution policy.
The following example sets the execution policy of PowerShell to
RemoteSigned
.
{
"Microsoft.PowerShell:ExecutionPolicy": "RemoteSigned"
}
For more information, see about_Execution_Policies.
PowerShellPolicies
Windows has several settings that can be managed by Group Policy. Usually,
those setting are stored in the Windows registry. Those setting can also be
defined in the powershell.config.json
file.
The PowerShellPolicies
is a JSON object that contains key-value pairs for the
various policy settings. Those policy settings can also be listed at the root
level of the JSON file, outside of the PowerShellPolicies
object. This
setting can contain the following subkeys:
ConsoleSessionConfiguration
ModuleLogging
ProtectedEventLogging
ScriptBlockLogging
ScriptExecution
Transcription
UpdatableHelp
The ScriptExecution
setting is used to set the PowerShell Execution Policy.
This takes precedence over the ExecutionPolicy
setting described above.
Example:
{
"PowerShellPolicies": {
"ScriptExecution": {
"ExecutionPolicy": "RemoteSigned"
}
}
}
For descriptions of the other policy settings, see the descriptions in the Common configuration settings section.
On Windows, PowerShell looks for the settings in the registry. Any settings
found in the registry have precedence. Next PowerShell reads the JSON
configuration. Any settings found under PowerShellPolicies
, and not defined
in the registry, take precedence over settings found at the root level of the
JSON configuration.
For more information, see about_Group_Policy_Settings.
Settings for non-Windows platforms
The following settings only apply to Linux and macOS platforms.
The following keys are used to configure PowerShell's logging for Linux and macOS.
LogChannels
LogIdentity
LogKeywords
LogLevel
For a full description of PowerShell logging for non-Windows systems, see about_Logging_Non-Windows.
Common configuration settings
The following settings are available on all supported platforms.
ConsoleSessionConfiguration
ExperimentalFeatures
ModuleLogging
ProtectedEventLogging
PSModulePath
ScriptBlockLogging
ScriptExecution
Transcription
UpdatableHelp
ConsoleSessionConfiguration
This setting specifies the session configuration to be used for all PowerShell sessions. This can be any endpoint registered on the local machine including the default PowerShell remoting endpoints or a custom endpoint having specific user role capabilities.
This key contains two subkeys:
EnableConsoleSessionConfiguration
- to enable session configurations, set the value totrue
. By default, this value isfalse
.ConsoleSessionConfigurationName
- Specifies the name of configuration endpoint in which PowerShell is run. By default, there is no session defined.
{
"ConsoleSessionConfiguration": {
"EnableConsoleSessionConfiguration": false,
"ConsoleSessionConfigurationName" : []
}
}
For more information, see about_Session_Configurations.
ExperimentalFeatures
The names of the experimental features to enable in PowerShell. The default value is an empty array.
The following example enables the PSCommandNotFoundSuggestion and PSSubsystemPluginModel experimental features when PowerShell starts up.
Example:
{
"ExperimentalFeatures": [
"PSCommandNotFoundSuggestion",
"PSSubsystemPluginModel"
]
}
For more information on experimental features, see Using experimental features.
ModuleLogging
This setting controls the behavior of logging for PowerShell modules. The setting contains two subkeys:
EnableModuleLogging
- to enable module logging, set the value totrue
. When enabled, pipeline execution events for members of the specified modules are recorded in the PowerShell log files.ModuleNames
- Specifies the name of the modules that should be logged.
Example:
{
"ModuleLogging": {
"EnableModuleLogging": true,
"ModuleNames" : [
"PSReadLine",
"PowerShellGet"
]
}
}
ProtectedEventLogging
This setting lets you configure Protected Event Logging. The setting contains two subkeys:
EnableProtectedEventLogging
- If you enable this policy setting, components that support it use the certificate you supply to encrypt log data before writing it to the log. Data is encrypted using the Cryptographic Message Syntax (CMS) standard. You can useUnprotect-CmsMessage
to decrypt these encrypted messages, if you have access to the private key of the certificate.EncryptionCertificate
- Provides a list of name of certificates to be used for encryption.
Example:
{
"ProtectedEventLogging": {
"EnableProtectedEventLogging": false,
"EncryptionCertificate": [
"Joe"
]
}
}
PSModulePath
Overrides the PSModulePath
settings for this PowerShell session. If the
configuration is for the current user, sets the CurrentUser module path. If
the configuration is for all users, sets the AllUsers module path.
Warning
Configuring an AllUsers or CurrentUser module path here doesn't change the scoped installation location for PowerShellGet cmdlets like Install-Module. These cmdlets always use the default module paths.
If no value is set, PowerShell uses the default value for the respective module path setting. For more information about these defaults, see about_PSModulePath.
This setting allows environment variables to be used by embedding them between
%
characters, like "%HOME%\Documents\PowerShell\Modules"
, in the same way
that the Windows Command Shell allows. This syntax also applies on Linux and
macOS. See below for examples.
This example shows a PSModulePath
configuration for a Windows environment:
{
"PSModulePath": "C:\\Program Files\\PowerShell\\6\\Modules"
}
This example shows a PSModulePath
configuration for a macOS or Linux
environment:
{
"PSModulePath": "/opt/powershell/6/Modules"
}
This example shows embedding an environment variable in a PSModulePath
configuration. Note that using the HOME
environment variable and the /
directory separator, this syntax works on Windows, macOS, and Linux.
{
"PSModulePath": "%HOME%/Documents/PowerShell/Modules"
}
This example uses an environment variable that only works on macOS and Linux:
{
"PSModulePath": "%XDG_CONFIG_HOME%/powershell/Modules"
}
Note
PowerShell variables can't be embedded in PSModulePath
configurations.
PSModulePath
configurations on Linux and macOS are case-sensitive. A
PSModulePath
configuration must use valid directory separators for the
platform. On macOS and Linux, this means /
. On Windows, both /
and \
work.
ScriptBlockLogging
This setting controls logging of all PowerShell script input. This setting contains two subkeys:
EnableScriptBlockLogging
- If you enable this policy setting, PowerShell logs the processing of commands, script blocks, functions, and scripts whether invoked interactively, or through automation.EnableScriptBlockInvocationLogging
- enables logging of script block start and stop events.
Example:
"ScriptBlockLogging": {
"EnableScriptBlockInvocationLogging": true,
"EnableScriptBlockLogging": false
}
Transcription
This policy setting lets you capture the input and output of PowerShell commands in text-based transcripts. If you enable this policy setting, PowerShell enables transcription for all PowerShell sessions.
This setting controls how transcription works in PowerShell. This setting contains three subkeys:
EnableTranscripting
- When this setting is enabled, PowerShell creates transcription log files in the configured location.EnableInvocationHeader
- By default, PowerShell includes a header at the top of the transcription log file. You can disable the header using this setting.OutputDirectory
- This setting allows you to collect transcription log files in a central location instead of the default location.
Example:
{
"Transcription": {
"EnableTranscripting": true,
"EnableInvocationHeader": true,
"OutputDirectory": "c:\\tmp"
}
}
For more information, see Start-Transcript.
UpdatableHelp
This policy setting allows you to set the default value of the SourcePath
parameter on the Update-Help
cmdlet. This default value can be overridden by
specifying a different value using the SourcePath parameter.
Example:
{
"UpdatableHelp": {
"DefaultSourcePath": "f:\\temp"
}
}