gsudo is a sudo
equivalent for Windows, with a similar user-experience as the original *nix sudo.
It allows either to run commands with elevated permissions on the current console, or to elevate the current shell, or launch elevated commands on a new console.
Just prepend gsudo
(or the sudo
alias) to your command and it will run elevated. (UAC popup will appear just once per session).
But why use gsudo
instead of some-other-sudo
?
- There are 3 types of sudo's available for Windows
- The ones that launches the elevated command on a new window.
- The ones that attaches the elevated console to the non-elevated console:
This is the best user experience within the current console, but does not allows to capture or redirect StdIn/Out/Err like
sudo dir | grep Bytes Free > FreeSpace.txt
- Those streaming StdIn/Out/Err to the non-elevated console. This allows to capture or redirect StdIn/Out/Err but has limited user experience: Elevated processes can only append plain text to the console, so text formatting, full screen console apps, progress bars, tab-key auto-complete, does not work.
gsudo
combines all three methods, and automatically uses the one that best fits your scenario, so you get the best user experience everytime.
- Elevated commands are shown in the user-level console. (Unless you specify
-n
which opens a new window.) - Credentials cache: If
gsudo
is invoked several times within minutes it only shows the UAC pop-up once. - CMD commands:
gsudo md folder
(no need to use the longer formgsudo cmd.exe /c md folder
) - Supports PowerShell/PowerShell Core commands.
- Supports being used on scripts:
gsudo
can be used on scripts that requires to elevate one or more commands. (the UAC popup will appear once).- Outputs of the elevated commands can be interpreted: E.g. StdOut/StdErr can be piped or captured (
gsudo dir | findstr /c:"bytes free" > FreeSpace.txt
) and exit codes too ('%errorlevel%)). Ifgsudo
fails to elevate, the exit code will be 999. - If
gsudo
is invoked (with params) from an already elevated console it will just run the command. So you don't have to worry if you rungsudo
or a script that usesgsudo
from an already elevated console. It also works. (The UAC popup will not appear)
Scoop users:
scoop install gsudo
Chocolatey users:
choco install gsudo
:: update Path environment variable
refreshenv
Manual installation: (no elevation required)
PowerShell -Command "Set-ExecutionPolicy RemoteSigned -scope Process; iwr -useb https://raw.githubusercontent.com/gerardog/gsudo/master/installgsudo.ps1 | iex"
gsudo
Opens an elevated shell in the current console.
gsudo [options] {command} [arguments]
Executes the specified command with elevated permissions.
Most relevant [options]
:
-n | --new
Starts the command in a new console with elevated rights (and returns immediately).-w | --wait
Force wait for the process to end (and return the exitcode).-s | --system
Run As Local System account ("NT AUTHORITY\SYSTEM").--copyev
Copy all environment variables to the elevated session before executing.--copyns
Reconnect current connected network shares on the elevated session. Warning! This is verbose, affects the elevated user system-wide (other processes), and can prompt for credentials interactively.--debug
Debug mode (verbose).
gsudo config
Show current user-settings.
gsudo config {key} ["value" | --reset]
Read, write, or reset a user setting to the default value.
Note: You can use anywhere the gsudo
command or the sudo
alias created by Scoop
or Chocolatey
installers.
Examples:
gsudo notepad %windir%\system32\drivers\etc\hosts
# sudo alias also available
sudo notepad %windir%\system32\drivers\etc\hosts
gsudo md "C:\Program Files\MyApp"
gsudo DISM /online /cleanup-image /scanhealth
# spawn the current shell (Cmd/PowerShell/PSCore) in a new console window
gsudo -n
# spawn PowerShell in a new console window
gsudo -n powershell
# launch in new window and wait for exit
gsudo -n -w powershell
# redirect/pipe input/output/error
gsudo dir | findstr /c:"bytes free" > FreeSpace.txt
# Configure Reduced logging
gsudo config LogLevel "Error"
# Configure a custom Elevated Prompt
gsudo config Prompt "$P [elevated]$G "
# Reset default Elevated Prompt
gsudo config Prompt --reset
gsudo
detects if it's invoked from PowerShell and allows the following syntax to elevate PS commands: You can pass a string literal with the command that needs to be elevated. PowerShell Quoting Rules apply.
Note that gsudo
returns a string that can be captured, not powershell objects.
PS C:\> gsudo 'powershell string command'
Examples:
# Commands without () or quotes
PS C:\> gsudo Remove-Item ProtectedFile.txt
or
PS C:\> gsudo 'Remove-Item ProtectedFile.txt'
# On strings enclosed in single quotation marks ('), escape " with \"
$hash = gsudo '(Get-FileHash \"C:\My Secret.txt\").Hash'
# For variable substitutions, use double-quoted strings with single-quotation marks inside
$hash = gsudo "(Get-FileHash '$file' -Algorithm $algorithm).Hash"
# or escape " with \""
$hash = gsudo "(Get-FileHash \""$file\"" -Algorithm $algorithm).Hash"
# Test gsudo success (optional):
if ($LastExitCode -eq 999 ) {
'gsudo failed to elevate!'
} elseif ($LastExitCode) {
'Command failed!'
} else { 'Success!' }
On WSL, elevation and root
are different concepts. WSL is a user application,root
allows full administation of WSL but not the windows system. Use WSL's native su
or sudo
to gain root
access. To get admin priviledge on the Windows box you need to elevate the WSL process. gsudo.exe
allows that (UAC popup will appear).
Use gsudo.exe
or sudo.exe
alias...(add .exe
)
# elevate default shell
PC:~$ gsudo.exe wsl
# run elevated Linux command
PC:~$ gsudo.exe wsl -e mkdir /mnt/c/Windows/MyFolder
# run elevated Windows command
PC:~$ gsudo.exe notepad C:/Windows/System32/drivers/etc/hosts
PC:~$ gsudo.exe "notepad C:\Windows\System32\drivers\etc\hosts"
gsudo.exe cmd /c "echo 127.0.0.1 www.MyWeb.com >> %windir%\System32\drivers\etc\hosts"
# test for gsudo and command success
retval=$?;
if [ $retval -eq 0 ]; then
echo "Success";
elif [ $retval -eq $((999 % 256)) ]; then # gsudo failure exit code (999) is read as 231 on wsl (999 mod 256)
echo "gsudo failed to elevate!";
else
echo "Command failed with exit code $retval";
fi;
Scoop
shim messes CTRL-C behaviour.Chocolatey
not afected. Quick fix, open CMD as admin, then:
del %userprofile%\scoop\shims\gsudo.exe
del %userprofile%\scoop\shims\sudo.exe
mklink %userprofile%\scoop\shims\gsudo.exe %userprofile%\scoop\apps\gsudo\current\gsudo.exe
mklink %userprofile%\scoop\shims\sudo.exe %userprofile%\scoop\apps\gsudo\current\gsudo.exe
- Elevated instances do not share the non-elevated user environment variables or network drives. This is not actually a
gsudo
issue but how Windows works. Options--copyEV
and--copyNS
replicates Environment Variables and Network Shares into the elevated session, but they are not bi-directional nor flawless. Network share reconnection can prompt for user/password. - Please report issues in the Issues section.
-
Why is it named
gsudo
instead of justsudo
?When I created
gsudo
, there were othersudo
packages on most Windows popular package managers such asChocolatey
andScoop
, so I had no other choice to pick another name.gsudo
installers on Scoop and Chocolatey create aliases forsudo
, so feel free to use thesudo
alias on your command line to invokegsudo
. -
Why
.Net Framework 4.6
?Because 4.6 is included in every Windows 10 installation.
.Net Core
requires additional installation steps and provides no substantial benefit since gsudo is Windows-specific, (other platforms can use the standard *nix sudo.) -
Want to know more?
Check the internals page.