Repository navigation
Description
Related: #5152
Using Start-Process to invoke console (terminal) programs is (almost always) inappropriate, but, unfortunately, very common - instead, such programs should be invoked by direct invocation / via &, the call operator.
Proper guidance at the start of the Start-Process topic would go a long way to help clear up the confusion:
Note: Start-Process launches the new process asynchronously by default; add -Wait to wait for the newly created process to terminate.
-
DO NOT use
Start-Processif you want to run a console (terminal-based) program synchronously, in the same window, with its standard streams connected to PowerShell's streams and the exit code reflected in$LASTEXITCODE- just invoke such a program directly / via&
(e.g.whoami.exeor& whoami.exerather thanStart-Process whoami.exe).-
Even if you use
Start-Process -NoNewWindow -Wait, you won't be able to capture or redirect the program's output (you can only save stdout and stderr (separately) to files, as text, via-RedirectStandardOutand-RedirectStandardError). Additionally, the process' exit code will not be reflected in$LASTEXITCODEwhen you useStart-Process. -
However, if your use case really calls for
Start-Process(see below) and you need to obtain the process exit code, you can add-PassThruto theStart-Processcall, which returns a process-information object (System.Diagnostics.Process) whose.ExitCodeproperty can be examined after the newly launched process has exited, which you can ensure by also passing-WaittoStart-Process, or by calling.WaitForExit()on the object later, or by checking if.HasExitedindicates$true.
-
-
[Only needed on Unix] DO use
Start-Processto launch a GUI program asynchronously on Unix-like platforms (e.g.,Start-Proces gedit).- Note: On Windows, GUI programs launch asynchronously even with direct invocation /
&, soStart-Process NotepadandNotepadhave the same effect.
- Note: On Windows, GUI programs launch asynchronously even with direct invocation /
-
[Only needed on Unix] DO use
Start-Processto launch a detached process via the standardnohuputility, i.e. a process that will run invisibly, detached from the calling terminal, sending its output to a file.- Note: On Windows, you can achieve a similar effect by launching with
-WindowStyle Hidden(albeit without automatic saving of output in a file).
- Note: On Windows, you can achieve a similar effect by launching with
-
[Windows-only] DO use
Start-Processfor starting console applications in a new window.-
On Unix-like platforms,
-NoNewWindowis invariably implied, and use ofStart-Processfor console programs there only makes sense if either (a) they neither prompt for input nor produce output or (b)-Waitis also used - but then direct invocation /&is the better choice - see The Start-Process topic contains incorrect and misleading information about use on Unix-like platforms #3013 -
[Windows-only] With
-WindowStyle <style>you can additionally control the new process' window style (both for console windows and the windows of GUI applications, though they latter may not respect the setting), such as whether to start the window maximized, minimized, or even hidden (see next point).
-
-
[Windows-only] DO use
Start-Process -WindowStyle Hidden, if you want to launch a process hidden. -
[Windows-only] DO use
Start-Processwith-Verb RunAsin order to launch a process elevated (with administrative privileges, with triggers a UAC security prompt), invariably in a new window.- Caveat:
-Verb RunAscannot be combined with the-RedirectStandard*parameters, so if you want to capture the elevated process' output in files, you'll need to launch a shell process with a command line that uses that shell's redirection features from inside the elevated process, along the lines ofStart-Process -Verb RunAs cmd.exe '/c "net session > out.txt"'
- Caveat:
-
[Windows-only] DO use
Start-Processwith-Credentialif you want to launch a process with a different user identity, invariably in a new window.- Caveat: This can not be combined with
-Verb RunAs, so in order to run as a different user and with elevation,Start-Processcalls must be nested, as demonstrated in this Stack Overflow answer.
- Caveat: This can not be combined with
From a cross-platform perspective, the short of it is:
- On Unix-like platforms,
Start-Processis useless except for two (unusual) scenarios: launching a GUI application asynchronously and launching a detached process vianohup
Document Details
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
- ID: fa4b8de4-3ea1-4210-4562-b084b0a51c0d
- Version Independent ID: ab184c39-041b-588c-acde-f715f6d3aee2
- Content: Start-Process (Microsoft.PowerShell.Management)
- Content Source: reference/7.0/Microsoft.PowerShell.Management/Start-Process.md
- Product: powershell
- GitHub Login: Dongbo Wang (@daxian-dbw)
- Microsoft Alias: dongbow
Activity
mi-hol commentedon Mar 23, 2021
Michael Klement (@mklement0) my use case is to start a new pwsh process with elevated administrator permission from a standard user as I try to emulate 'sudo'.
From my understanding impersonation using the -Credential paramater is only available in Start-Process.
Note: search for "-Credential" in online documentation gives tons of false positive search hits :(
Do I miss an obvious alternative that would avoid above mentioned drawbacks and issues?
mklement0 commentedon Mar 23, 2021
Good point, mi-hol: I forgot to include the
-Verb RunAsand-Credentialuse cases.Note that they cannot be combined, however; if you do need to combine them - which in the typical case simply means that the admin user name is pre-populated in the UAC dialog, but you'll still have to supply the password interactively - you'll have to nest
Start-Processcalls.I've updated the initial post, including with a link to a Stack Overflow answer that shows the nesting technique.
mi-hol commentedon Mar 23, 2021
Thanks mklement I had used the nested Start-Process calls already.
I noticed thought that on my tests this technique works only with Windows powershell as the shell to run a second elevated pwsh.
Not sure if this is "by design" or a bug in pwsh's Windows compatibility.
Working example with Windows powershell:
Failing example with pwsh:
mklement0 commentedon Mar 30, 2021
mi-hol, you're missing the
-Command/-cparameter in thepwsh.exeexample:(
powershell.exedefaults to-c, butpwsh.exenow defaults to-file, so as to support Unix shebang lines):wikiped commentedon Dec 1, 2021
Another point that deserves to be added to the list:
Start-Processwith-Verb RunAswhen you want to capture StandardOutput / StandardError from elevated process - there is NO built-in way to do that.This, of course, leaves out the answer to the question what is the obvious 'Powershell way' to do it. And it seems there is none. Assuming that resorting to
New-Object System.Diagnostics.Processis not really a 'Powershell way' to get it done.mklement0 commentedon Dec 1, 2021
Thanks, wikiped, good point. Please see my update to the initial post; I've folded the information as caveat into the bullet point about
-Verb RunAs, and I've also included the only solution I'm aware of (direct use ofSystem.Diagnostics.Processwouldn't help, the limitation is likely at the level of the WinAPI).wikiped commentedon Dec 3, 2021
Thank you Michael Klement (@mklement0) for updating the list. I was struggling with
System.Diagnostics.Processto get it working and do realize now that it won't help either. There is basically no way to make elevated process return its result back to the calling process. They are completely different processes at the end and it is necessary to use one of IPC approaches:Writing to file on disk is probably the easiest to implement among those.
mklement0 commentedon Dec 3, 2021
wikiped, saving to files is the only thing that
Start-Processitself offers, and the initial post now shows a workaround for how to achieve that in combination with-Verb RunAs: by launching the target program indirectly, via a shell process whose own redirection features can then be used.As for IPC approaches: I haven't dug deeper, but I suspect that pipes and events aren't an option for security reasons (prevented by design, at least with respect to the standard streams), and that a TCP/IP-based mechanism would require both the caller and the elevated callee to be explicitly designed for that.
yair-mantis commentedon Jun 17, 2022
thanks for this, a small tuning
i would link to the call operator &, as that is how its referred in the docs.
mklement0 commentedon Jun 17, 2022
Thanks, yair-mantis - I've updated the initial post accordingly.
Fixes #6239 - Document appropriate use of Start-Process (#9168)
yecril71pl commentedon Dec 13, 2022
Note: the remark no prompt for input was not included in the fix. This is probably a good thing because this description is too vague. I understand that
pwshdoes not offer job control so whether it prompts or not, the input it will get from standard input will be empty unless redirected, which may but need not be OK. But it can prompt for input using another communication channel and produce its output elsewhere too, especially if it runs as a daemon likeftpdfor example.