gsudo is a sudo equivalent for Windows, with a similar user-experience as the original Unix/Linux sudo.
Allows you to run a command (or re-launch your current shell) with elevated permissions, in the current console window or a new one.
Just prepend gsudo (or the sudo alias) to your command and it will run elevated. For PowerShell use this syntax: gsudo { ScriptBlock }
One UAC popup will appear each time. You can see less popups if you enable gsudo cache.
It detects your current shell and elevates your command as native shell commands. (Supports Cmd, PowerShell, WSL, git-bash, MinGW, Cygwin, Yori, Take Command, BusyBox & NuShell.)
⭐ Extended documentation available at: https://gerardog.github.io/gsudo/
(with gsudo config CacheMode auto)
-
Elevated commands are shown in the current console. No new window (unless you specify
-n) -
Credentials cache:
gsudocan elevate many times showing only one UAC pop-up if the user opts-in to enable the cache. -
Detects your current shell (Supports
CMD,PowerShell,WSL,Bash for Windows(Git-Bash/MinGW/MSYS2/Cygwin),Yori,Take CommandandNuShell), and elevates your command correctly. -
Supports being used on scripts:
- Outputs StdOut/StdErr can be piped or captured (e.g.
gsudo dir | findstr /c:"bytes free" > FreeSpace.txt) and exit codes too (%errorlevel%). Ifgsudofails to elevate, the exit code will be 999. - If
gsudois invoked from an already elevated console, it will just run the command (it won't fail). So, you don't have to worry if you rungsudoor a script that usesgsudofrom an already elevated console. (The UAC popup will not appear, as no elevation is required)
- Outputs StdOut/StdErr can be piped or captured (e.g.
-
gsudo !!elevates the last executed command. Works on CMD, Git-Bash, MinGW, Cygwin (and PowerShell with gsudo module only)
- Using Scoop:
scoop install gsudo - Using WinGet:
winget install gerardog.gsudo - Using Chocolatey:
choco install gsudo - Running this line: (script):
PowerShell -Command "Set-ExecutionPolicy RemoteSigned -scope Process; [Net.ServicePointManager]::SecurityProtocol = 'Tls12'; iwr -useb https://raw.githubusercontent.com/gerardog/gsudo/master/installgsudo.ps1 | iex"
- Portable:
- Download
gsudo.portable.zipfrom the latest release - Extract the folder corresponding to your processor architecture (x64, x86, or arm64) from the zip file to a suitable directory on your computer.
- Optionally, add that directory to your system's PATH environment variable if it's not already accessible.
- Download
Please restart all your console windows after installing to ensure that the PATH environment variable is refreshed.
Note: gsudo.exe is portable. No windows service is required or system change is done, except adding it to the Path.
gsudo [options] # Starts your current shell elevated
gsudo [options] {command} [args] # Runs {command} with elevated permissions
gsudo cache [on | off | help] # Starts/Stops a credentials cache session. (less UAC popups)
gsudo status [--json | filter ] # Shows current user, cache and console status.
gsudo !! # Re-run last command as admin. (YMMV)New Window options:
-n | --new # Starts the command in a new console/window (and returns immediately).
-w | --wait # When in new console, wait for the command to end.
--keepShell # After running a command, keep the elevated shell open.
--keepWindow # After running a command in a new console, ask for keypress before closing the console/window.
Security options:
-u | --user {usr} # Run as the specified user. Asks for password. For local admins shows UAC unless '-i Medium'
-i | --integrity {v} # Specify integrity level: Untrusted, Low, Medium, MediumPlus, High (default), System
-s | --system # Run as Local System account (NT AUTHORITY\SYSTEM).
--ti # Run as member of NT SERVICE\TrustedInstaller
-k # Kills all cached credentials. The next time gsudo is run a UAC popup will be appear.
Shell related options:
-d | --direct # Skips Shell detection. Assume CMD shell or CMD {command}.
--loadProfile # When elevating PowerShell commands, load user profile.
Other options:
--loglevel {val} # Set minimum log level to display: All, Debug, Info, Warning, Error, None
--debug # Enable debug mode.
--copyns # Connect network drives to the elevated user. Warning: Verbose, interactive asks for credentials
--copyev # (deprecated) Copy environment variables to the elevated process. (not needed on default console mode)
--chdir {dir} # Change the current directory to {dir} before running the command.Note: You can use anywhere the sudo alias created by the installers.
Examples:
gsudo # elevates the current shell in the current console window (Supports Cmd/PowerShell/Pwsh Core/Yori/Take Command/git-bash/cygwin)
gsudo -n # launch the current shell elevated in a new console window
gsudo -n -w powershell ./Do-Something.ps1 # launch in new window and wait for exit
gsudo notepad %windir%\system32\drivers\etc\hosts # launch windows app
sudo notepad # sudo alias built-in
# redirect/pipe input/output/error example
gsudo dir | findstr /c:"bytes free" > FreeSpace.txt
gsudo config LogLevel "Error" # Configure Reduced logging
gsudo config Prompt "$P [elevated]$G " # Configure a custom Elevated Prompt
gsudo config Prompt --reset # Reset to default value
# Enable credentials cache (less UAC popups):
gsudo config CacheMode Autogsudo detects if invoked from PowerShell and elevates PS commands (unless -d is used to elevate CMD commands).
The command to elevate will run in a different process, so it can't access the parent $variables and scope.
To elevate a commands or script block: Wrap it in {curly braces}.
# Syntax:
gsudo { ScriptBlock }
gsudo [options] { ScriptBlock } [-args $argument1[..., $argumentN]] ;
# Examples:
gsudo { Write-Output "Hello World" }
# Pass arguments with -args
$MyString = "Hello World"
gsudo { Write-Output $args[0] } -args $MyString
# Output is serialized as PSObjects with properties.
$services = gsudo { Get-Service 'WSearch', 'Winmgmt'}
Write-Output $services.DisplayName
# Inputs too: Example elevated iteration of a list.
Get-ChildItem . | gsudo { $Input.CreationTime}Alternative syntaxes:
2. Invoke-gsudo wrapper function: (much slower)
# Pass values (not variables by reference) by prefixing `$using:`. I.E.
$MyString = "Hello World"
Invoke-Gsudo { Write-Output $using:MyString }
# Syntax:
Invoke-Gsudo [-ScriptBlock] <ScriptBlock>
[[-ArgumentList] <Object[]>]
[-InputObject <PSObject>]
[-LoadProfile | -NoProfile]
[-Credential <PSCredential>]- PowerShell function.
- Performs auto serialization of inputs & outputs.
- You can prefix variables with the `$using:` scope modifier (like `$using:variableName`) and their serialized value is applied.
- Use `-LoadProfile` or `-NoProfile` to override profile loading or not.
- Use `-Credential` option for Run As User (same as `-u` but for `Get-Credentials`).
- Better forwarding of your current context to the elevated instance (current Location, $ErrorActionPreference)
3. Manual string interpolation. (not recommended)
I don't recommend this approach as it is really hard to do proper escape all special characters.Usage: gsudo 'string literal'
# Variable substitutions example:
$file='C:\My Secret.txt';
$algorithm='md5';
$hash = gsudo "(Get-FileHash '$file' -Algorithm $algorithm).Hash"
# or
$hash = gsudo "(Get-FileHash ""$file"" -Algorithm $algorithm).Hash"- Accepts a string literal with the command to elevate.
- Returns a list of strings.
-
Optional: Import module
gsudoModule.psd1into your PowerShell Profile:- Adds syntax auto-complete to gsudo in PowerShell. Plus, it suggests the 3 previous commands, making your workflow smoother than ever!
- Enables
gsudo !!on Powershell, to elevate the last executed command. - Adds Functions:
Test-IsGsudoCacheAvailableReturns true if a gsudo cache is active (meaning elevation with no UAC is possible).Test-IsProcessElevated: Returns true if the current process is elevated.Test-IsAdminMember: Returns true if the current user is member of theLocal Administratorsgroups, which means it can elevate with.
# Add the following line to your $PROFILE Import-Module "gsudoModule" # Or run: Write-Output "`nImport-Module `"gsudoModule`"" | Add-Content $PROFILE
- If you haven't already customized your PowerShell prompt (for example by installing Oh-My-Posh), you can easily add a red
#indicating that the current process is elevated:
To do so add this line to your profile (after importing
gsudoModule):Set-Alias Prompt gsudoPrompt
On WSL, elevation and root are different concepts. root allows full administration of WSL but not the windows system. Use WSL's native su or sudo to gain root access. To get admin privilege on the Windows box you need to elevate the WSL.EXE process. gsudo allows that (a UAC popup will appear).
On WSL bash, prepend gsudo to elevate WSL commands or gsudo -d for CMD commands.
# elevate default shell
PC:~$ gsudo
# run elevated WSL command
PC:~$ gsudo mkdir /mnt/c/Windows/MyFolder
# run elevated Windows command
PC:~$ gsudo -d notepad C:/Windows/System32/drivers/etc/hosts
PC:~$ gsudo -d "notepad C:\Windows\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; gsudo config # Show current config settings & values.
gsudo config {key} [--global] [value] # Read or write a user setting
gsudo config {key} [--global] --reset # Reset config to default value
--global # Affects all users (overrides user settings)The Credentials Cache, if enabled and active, allows to elevate several times from a parent process with only one UAC pop-up. After 5 minutes without elevations, the cache session closes automatically (Configurable timeout via gsudo config CacheDuration).
While this very convenient, it's important to understand its potential security risks. Even if gsudo itself is secure, the inherent vulnerability lies in the host process. If your system is already compromised by a malicious process, it can manipulate the permitted process (e.g., Cmd/Powershell) and force an active gsudo cache instance to elevate privileges without triggering a UAC prompt.
This risk is the trade-off for using the Credentials Cache. The cache is safe to use as long as you are confident there are no malicious processes running on your system.
Here are the Credentials Cache Modes:
Explicit:(default) Every elevation shows a UAC popup, unless a cache session is started manually...- To start or stop a cache session run:
gsudo cache {on | off} - This is the default mode. (Use
gsudo config CacheMode Explicitto revert to this value).
- To start or stop a cache session run:
Auto:Similar to unix-sudo. The first elevation shows a UAC popup and starts a cache session automatically.- Run
gsudo config CacheMode Autoto use this mode.
- Run
Disabled:Every elevation shows a UAC popup, and trying to start a cache session will throw an error..- Run
gsudo config CacheMode Disabledto use this mode.
- Run
In any case, you can stop all cache sessions with gsudo -k.
-
The elevated instances do not have access to the network shares connected on the non-elevated space. This is not a
gsudoissue but how Windows works. Use--copyNSto replicate Network Shares into the elevated session, but this is not bi-directional and is interactive (may prompt for user/password). -
gsudo.execan be placed on a network share and invoked as\\server\share\gsudo {command}but doesn't work if your current folder is a network drive. For example do not map\\server\share\toZ:and thenZ:\>gsudo do-something. -
Please report issues in the Issues section.
-
Why is it named
gsudoinstead of justsudo?When I created
gsudo, there were othersudopackages on most Windows popular package managers such asChocolateyandScoop, so I had no other choice to pick another name.gsudoinstallers create an alias forsudo, so feel free to usesudoon your command line to invokegsudo. -
Why did you migrated from
.Net Framework 4.6to.Net Core 7.0?Starting from v1.4.0, it is built using
.Net 7.0NativeAOT. It loads faster and uses less memory, and runs on machines without any .Net runtime installed. Prior versions<v1.3.0used .Net 4.6, because it was included in every Windows 10/11 installation. -
Is
gsudoa port of*nix sudo?No.
gsudoreminds of the original sudo regarding user expectations. Manysudofeatures are*nixspecific and could never have aWindowscounterpart. Other features (such assudoers) could potentially be implemented but are not at this point. -
What are the requirements? Does it work in Windows 7/8?
It works on Win7 SP1 onwards. Some features may only work in Windows 10/11, like elevating as TrustedInstaller.
-
How do I return to the previous security level after using gsudo?
In the same way as you would with
Unix/Linux sudo:gsudodoes not alter the current process, instead it launches a new process with different permissions/integrity level. To go back to the previous level, just end the new process. ForCommand PromptorPowerShelljust typeexit.
- Please give us a star! ⭐
- Help spread the word by mentioning
gsudoin social networks! - Sponsor or Donate
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent