Start-Process

Syntax

Start-Process
     [-FilePath] <String>
     [[-ArgumentList] <String[]>]
     [-Credential <PSCredential>]
     [-WorkingDirectory <String>]
     [-LoadUserProfile]
     [-NoNewWindow]
     [-PassThru]
     [-RedirectStandardError <String>]
     [-RedirectStandardInput <String>]
     [-RedirectStandardOutput <String>]
     [-WindowStyle <ProcessWindowStyle>]
     [-Wait]
     [-UseNewEnvironment]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Start-Process
     [-FilePath] <String>
     [[-ArgumentList] <String[]>]
     [-WorkingDirectory <String>]
     [-PassThru]
     [-Verb <String>]
     [-WindowStyle <ProcessWindowStyle>]
     [-Wait]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Description

The Start-Process cmdlet starts one or more processes on the local computer. By default, Start-Process creates a new process that inherits all the environment variables that are defined in the current process.

To specify the program that runs in the process, enter an executable file or script file, or a file that can be opened using a program on the computer. If you specify a non-executable file, Start-Process starts the program that's associated with the file, similar to the Invoke-Item cmdlet.

You can use the parameters of Start-Process to specify options, such as loading a user profile, starting the process in a new window, or using alternate credentials.

Examples

Example 1: Start a process that uses default values

This example starts a process that uses the Sort.exe file in the current folder. The command uses all the default values, including the default window style, working folder, and credentials.

Start-Process -FilePath "sort.exe"

Example 2: Print a text file

This example starts a process that prints the C:\PS-Test\MyFile.txt file.

Start-Process -FilePath "myfile.txt" -WorkingDirectory "C:\PS-Test" -Verb Print

Example 3: Start a process to sort items to a new file

This example starts a process that sorts items in the TestSort.txt file and returns the sorted items in the Sorted.txt files. Any errors are written to the SortError.txt file. The UseNewEnvironment parameter specifies that the process runs with its own environment variables.

$processOptions = @{
    FilePath = "sort.exe"
    RedirectStandardInput = "TestSort.txt"
    RedirectStandardOutput = "Sorted.txt"
    RedirectStandardError = "SortError.txt"
    UseNewEnvironment = $true
}
Start-Process @processOptions

This example uses splatting to pass parameters to the cmdlet. For more information, see about_Splatting.

Example 4: Start a process in a maximized window

This example starts the Notepad.exe process. It maximizes the window and retains the window until the process completes.

Start-Process -FilePath "notepad" -Wait -WindowStyle Maximized

Example 5: Start PowerShell as an administrator

This example starts PowerShell using the Run as administrator option.

Start-Process -FilePath "powershell" -Verb RunAs

Example 6: Using different verbs to start a process

This example shows how to find the verbs that can be used when starting a process. The available verbs are determined by the filename extension of the file that runs in the process.

$startExe = New-Object System.Diagnostics.ProcessStartInfo -Args powershell.exe
$startExe.verbs

open
runas
runasuser

The example uses New-Object to create a System.Diagnostics.ProcessStartInfo object for powershell.exe, the file that runs in the PowerShell process. The Verbs property of the ProcessStartInfo object shows that you can use the Open and RunAs verbs with powershell.exe, or with any process that runs a .exe file.

Example 7: Specifying arguments to the process

Both commands start the Windows command interpreter, issuing a dir command on the Program Files folder. Because this foldername contains a space, the value needs surrounded with escaped quotes. Note that the first command specifies a string as ArgumentList. The second command is a string array.

Start-Process -FilePath "$env:comspec" -ArgumentList "/c dir `"%SystemDrive%\Program Files`""
Start-Process -FilePath "$env:comspec" -ArgumentList "/c","dir","`"%SystemDrive%\Program Files`""

Example 8: Create a detached process on Linux

On Windows, Start-Process creates an independent process that remains running independently of the launching shell. On non-Windows platforms, the newly started process is attached to the shell that launched. If the launching shell is closed, the child process is terminated.

To avoid terminating the child process on Unix-like platforms, you can combine Start-Process with nohup. The following example launches a background instance of PowerShell on Linux that stays alive even after you close the launching session. The nohup command collects output in file nohup.out in the current directory.

# Runs for 2 minutes and appends output to ./nohup.out
Start-Process nohup 'pwsh -noprofile -c "1..120 | % { Write-Host . -NoNewline; sleep 1 }"'

In this example, Start-Process is running the Linux nohup command, which launches pwsh as a detached process. For more information, see the nohup article on Wikipedia.

Parameters

-ArgumentList

-Confirm

-Credential

-FilePath

-LoadUserProfile

-NoNewWindow

-PassThru

-RedirectStandardError

-RedirectStandardInput

-RedirectStandardOutput

-UseNewEnvironment

-Verb

-Wait

-WhatIf

-WindowStyle

-WorkingDirectory

Inputs

None

You can't pipe objects to this cmdlet.

Outputs

None

By default, this cmdlet returns no output.

Process

When you use the PassThru parameter, this cmdlet returns a Process object.

Notes

PowerShell includes the following aliases for Start-Process:

• All platforms
  • saps
• Windows
  • start

Native commands are executable files installed in the operating system. These executables can be run from any command-line shell, like PowerShell. Usually you run the command exactly as you would in bash or cmd.exe. The Start-Process cmdlet can be used to run any native commands, but should only be used when you need to control how the command is executed.

Start-Process is useful for running GUI programs on non-Windows platforms. For example, run Start-Proces gedit to launch the graphical text editor common the GNOME Desktop environments.

By default, Start-Process launches a process asynchronously. Control is instantly returned to PowerShell even if the new process is still running.

• On the local system, the launched process lives on independent from the calling process.
• On a remote system, the new process is terminated when the remote session ends, immediately following the Start-Process command. Therefore, you can't use Start-Process in a remote session expecting the launched process to outlive the session.

If you do need to use Start-Process in a remote session, invoke it with the Wait parameter. Or you could use other methods to create a new process on the remote system.

When using the Wait parameter, Start-Process waits for the process tree (the process and all its descendants) to exit before returning control. This is different than the behavior of the Wait-Process cmdlet, which only waits for the specified processes to exit.

On Windows, the most common use case for Start-Process is to use the Wait parameter to block progress until the new process exits. On non-Windows system, this is rarely needed since the default behavior for command-line applications is equivalent to Start-Process -Wait.

This cmdlet is implemented using the Start method of the System.Diagnostics.Process class. For more information about this method, see Process.Start Method.

Related Links

• about_Quoting_Rules
• Debug-Process
• Get-Process
• Start-Service
• Stop-Process
• Wait-Process