Skip to main content

How to Delete a Local Group in a Batch Script

When decommissioning an application, cleaning up a server, or restructuring permissions, you may need to delete a local group that is no longer needed. This action permanently removes the group from the local security database, and any permissions that were assigned to that group will no longer apply to its former members.

This guide will teach you how to use the standard, built-in NET LOCALGROUP command to safely and permanently delete a local group from a machine. You will learn the correct syntax, the essential prerequisite of checking the group's members before deletion, and the critical importance of running the script with administrator privileges.

danger

CRITICAL WARNING: Deleting a local group is an irreversible security operation. This can result in a permanent loss of access to files and resources for the users who were members of that group. There is no undo. This script must be run with full administrator privileges.

The Core Command: NET LOCALGROUP​

The NET.EXE utility is the primary tool for managing local users and groups from the command line. The LOCALGROUP context is used to create, modify, and delete local groups.

Syntax for Deletion: NET LOCALGROUP "GroupName" /DELETE

  • "GroupName": (Required) The name of the local group you want to delete. If the name contains spaces, it must be enclosed in quotes.
  • /DELETE: The switch that performs the delete operation.

Basic Example: Deleting a Group​

This script deletes a local group named "AppTesters".

@ECHO OFF
REM This script MUST be run as an Administrator.

SET "GroupName=AppTesters"

ECHO --- Deleting a local group ---
ECHO WARNING: This will permanently delete the group '%GroupName%'.
ECHO All permissions assigned to this group will be lost.
ECHO.
PAUSE
ECHO.

ECHO Deleting group...
NET LOCALGROUP "%GroupName%" /DELETE

IF %ERRORLEVEL% EQU 0 (
    ECHO [SUCCESS] The group was deleted successfully.
) ELSE (
    ECHO [FAILURE] An error occurred. Check if the group exists and if you are running as Admin.
)

3. The Essential Prerequisite: Checking Before Deleting​

Before you delete a group, it is a crucial safety step to see who its members are. This ensures you are not accidentally revoking access for important user accounts. You can do this by running NET LOCALGROUP with just the group name.

Command to list members: NET LOCALGROUP "GroupName"

C:\> NET LOCALGROUP "ReportViewers"
Alias name     ReportViewers
Comment        Members of this group can view weekly reports.

Members
-------------------------------------------------------------------------------
Alice
Bob
CORP\sjenkins
The command completed successfully.

By reviewing this list first, you can confirm that you are about to delete the correct group and that no critical accounts will be affected.

Key NET LOCALGROUP Parameters Explained​

  • GroupName: The name of the group.
  • /DELETE: Deletes a user from a group, or if a user is not specified, deletes the entire group.
  • /ADD: Adds a user to a group, or creates the group if it doesn't exist.
  • /COMMENT:"text": Adds or changes the group's comment.

Common Pitfalls and How to Solve Them​

  • "System error 5 has occurred. Access is denied.": This is the number one cause of failure. It means your script does not have the necessary permissions. Solution: You must run the script from an elevated command prompt ("Run as administrator").

  • "System error 1377 has occurred. The specified local group does not exist.": This error occurs if you try to delete a group that isn't on the system.

    • Solution: In a cleanup script, this is often not a critical failure; it just means the group is already gone. A robust script can check if the group exists before trying to delete it. 
      NET LOCALGROUP "%GroupName%" > NUL 2> NUL
      IF %ERRORLEVEL% EQU 0 (
          ECHO Group found. Deleting...
          NET LOCALGROUP "%GroupName%" /DELETE
      ) ELSE (
          ECHO Group not found. Nothing to do.
      )

  • Trying to Delete Built-in Groups: You cannot delete standard, built-in Windows groups like "Administrators", "Users", or "Remote Desktop Users".

    • The Error: System error 1371 has occurred. This group cannot be deleted.
    • Solution: This is a built-in safety feature. Your scripts should only ever target custom groups that you have created.

Practical Example: A Post-Uninstall Cleanup Script​

This script is designed to run after an application is uninstalled. It cleanly removes the custom local group that the application's installer had created.

@ECHO OFF
SETLOCAL
REM This script must be run as an Administrator.

SET "AppGroup=ProjectX_Editors"

ECHO --- Application Post-Uninstall Cleanup ---
ECHO This will remove the '%AppGroup%' local group.
ECHO.

REM --- Step 1: Check if the group exists before trying to delete it ---
ECHO Checking for group...
NET LOCALGROUP "%AppGroup%" > NUL 2> NUL

IF %ERRORLEVEL% NEQ 0 (
    ECHO [INFO] Group '%AppGroup%' does not exist. No action needed.
    GOTO :End
)

ECHO [ACTION] Group found. Deleting it now...
NET LOCALGROUP "%AppGroup%" /DELETE

IF %ERRORLEVEL% EQU 0 (
    ECHO [SUCCESS] Group deleted.
) ELSE (
    ECHO [FAILURE] Failed to delete group.
)

:End
ENDLOCAL

Conclusion​

The NET LOCALGROUP command is the standard, built-in tool for deleting local groups from a batch script. While the command is simple, the action is powerful and irreversible.

For a safe and reliable script:

  1. Always run your script as an Administrator.
  2. Use NET LOCALGROUP "GroupName" first to review the group's members as a safety check.
  3. Use the final command NET LOCALGROUP "GroupName" /DELETE to remove the group.
  4. Remember that this does not delete the user accounts that were members of the group, but it does revoke any permissions they had through that group.

Table of Contents