Running Scripts

Updated: August 9, 2012

Applies To: Windows PowerShell 2.0, Windows PowerShell 3.0

This topic explains what scripts are and how to run them in Windows PowerShell.

What is a script?

A script is text file that contains one or more Windows PowerShell commands or expressions. When you run the script, the commands and expressions in the script file run, just as if you typed them at the command line.

Typically, you write a script to save command sequence that you use frequently or to share a command sequence with others.

Scripts can be as simple as a one-line command or as complex as an application program. Windows PowerShell includes a very rich and powerful scripting language that is designed especially for people who are not programmers. It supports language constructs for looping, conditions, flow-control, variable assignment, and much more.

How to write a script

To write a script, start a text editor, such as Notepad, or a script editor, such as Windows PowerShell Integrated Scripting Environment (ISE). Type commands or expressions, just as you would type them at the command line. Then save them in a file with .ps1 file name extension.

For example, the following command finds scripts in your user profile directory ($home) and its subdirectories. The $Home automatic variable is equivalent to the %UserProfile% environment variable, which is written as $env:UserProfile in Windows PowerShell.

Get-ChildItem -Path $home\* -Include *.ps1 -Recurse

For more information about this command, type Get-Help about_Automatic_Variables and Get-Help Get-ChildItem.

To create the Get-Scripts.ps1 script, use the following procedure.

  1. Start Notepad.

  2. Paste the Get-ChildItem command (above) in the Notepad window.

  3. Save the file as Get-Scripts.ps1 in the current directory.

That's all there is to it. As you become more familiar with Windows PowerShell, you'll create more scripts and get scripts from colleagues and from safe websites.

We'll tell you how to run a script very soon, but before we do, we'll explain why your first attempt to run a script might fail.

How to allow scripts to run

Although scripts are extremely useful, even essential, they can be used to spread malicious code. To keep your computer secure, the default Windows PowerShell execution policy, Restricted, does not permit you to run scripts. And, to eliminate an obvious risk, none of the execution policies in Windows PowerShell allow you to run a script by double-clicking its icon.

To get the current execution policy, use the Get-ExecutionPolicy cmdlet, as follows.

Get-ExecutionPolicy

To change the execution policy for the computer, for particular users, or for particular sessions, use the Set-ExecutionPolicy cmdlet, as follows.

  1. Start Windows PowerShell with the "Run as Administrator" option. (For more information, see Starting Windows PowerShell.) Only members of the Administrators group on the computer can change the execution policy.

  2. Run the Set-ExecutionPolicycmdlet.

For example, the following command sets the execution policy for all users on the computer to RemoteSigned.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

The RemoteSigned execution policy requires a digital signature on scripts that you download or get from other computers, but it does not require a digital signature on scripts that you write on your local computer.

Windows PowerShell also supports the "Turn on script execution" Group Policy setting, which sets the execution policy for computers and users.

For more information, type:

Get-Help about_Execution_Policies

How to run scripts

To run a script, type the path and name of the script file. The path is required, even when the script is located in the current directory, to make it more difficult for malicious code to run scripts. The file name extension is optional and, as always, Windows PowerShell is not case sensitive.

For example, to run the Get-Scripts.ps1 script, type:

$home\Get-Scripts.ps1

The output should include the Get-Scripts.ps1 file, among others.

If the script is in the current directory, type the directory name or use a dot (.) to represent the current directory. For example, use the Set-Location command to go to the $home directory, as follows.

Set-Location $home

Then, use a dot to indicate the current directory in the path to the Get-Scripts.ps1 script.

.\Get-Scripts.ps1

How to get help for a script

To get help for a script, use the Get-Help cmdlet. Type "Get-Help" followed by the path and name of the script file.

For example:

Get-Help $home\Get-Scripts.ps1

Because we didn't write help for the Get-Scripts.ps1 script, Windows PowerShell auto-generates a help file from the script code, but most scripts come with a detailed help file. For information about writing help for a script, type Get-Help about_Comment_Based_Help.

Run with PowerShell

There is one more way to run scripts. It is designed for particular types of scripts, so you're likely to use it only occasionally, but it's very handy when you need it.

Beginning in Windows PowerShell 3.0, you can run scripts from File Explorer in Windows 8 and Windows Server 2012 and from Windows Explorer in earlier versions of Windows. The "Run with PowerShell" feature is designed to run scripts that do not have required parameters and do not return output to the command prompt.

To use the "Run with PowerShell" feature:

  • In File Explorer (or Windows Explorer), right-click the script file name and then select "Run with PowerShell."

The "Run with PowerShell" feature starts a Windows PowerShell session that has an execution policy of Bypass, runs the script, and closes the session.

For more information, type: Get-Help about_Run_With_PowerShell.

Troubleshooting Note: A Run with PowerShell command might prompt you to confirm the execution policy of the temporary session .

See Also

Other Resources

about_Scripts
about_Execution_Policies
about_Run_With_PowerShell