New-LocalUser
Creates a local user account.
Syntax
New-LocalUser
[-AccountExpires <DateTime>]
[-AccountNeverExpires]
[-Description <String>]
[-Disabled]
[-FullName <String>]
[-Name] <String>
-Password <SecureString>
[-PasswordNeverExpires]
[-UserMayNotChangePassword]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
New-LocalUser
[-AccountExpires <DateTime>]
[-AccountNeverExpires]
[-Description <String>]
[-Disabled]
[-FullName <String>]
[-Name] <String>
[-NoPassword]
[-UserMayNotChangePassword]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
The New-LocalUser
cmdlet creates a local user account. This cmdlet creates a local user account
or a local user account that is connected to a Microsoft account.
Note
The Microsoft.PowerShell.LocalAccounts module is not available in 32-bit PowerShell on a 64-bit system.
Examples
Example 1: Create a user account
PS C:\> New-LocalUser -Name "User02" -Description "Description of this account." -NoPassword
Name Enabled Description
---- ------- -----------
User02 True Description of this account.
This command creates a local user account and does not specify the AccountExpires or Password parameters. Therefore, the account doesn't expire or have a password by default.
Example 2: Create a user account that has a password
PS C:\> $Password = Read-Host -AsSecureString
PS C:\> New-LocalUser "User03" -Password $Password -FullName "Third User" -Description "Description of this account."
Name Enabled Description
---- ------- -----------
User03 True Description of this account.
The first command prompts you for a password by using the Read-Host
cmdlet. The command stores the
password as a secure string in the $Password
variable.
The second command creates a local user account by using the password stored in $Password
. The
command specifies a user name, full name, and description for the user account.
Parameters
Specifies when the user account expires. To obtain a DateTime object, use the Get-Date
cmdlet.
If you do not specify this parameter, the account does not expire.
Type: | DateTime |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Indicates that the account does not expire.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Prompts you for confirmation before running the cmdlet.
Type: | SwitchParameter |
Aliases: | cf |
Position: | Named |
Default value: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Specifies a comment for the user account. The maximum length is 48 characters.
Type: | String |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Indicates that this cmdlet creates the user account as disabled.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Specifies the full name for the user account. The full name differs from the user name of the user account.
Type: | String |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Specifies the user name for the user account.
If you create a local user account for the local system, the user name can contain up to 20 uppercase characters or lowercase characters. A user name cannot contain the following characters:
"
, /
, \
, [
, ]
, :
, ;
, |
, =
, ,
, +
, *
, ?
, <
, >
, @
A user name cannot consist only of periods .
or spaces.
Type: | String |
Position: | 0 |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Indicates that the user account does not have a password.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Specifies a password for the user account. You can use Read-Host -GetCredential
, Get-Credential
,
or ConvertTo-SecureString
to create a SecureString object for the password.
If you omit the Password and NoPassword parameters, New-LocalUser
prompts you for the new
user's password.
Type: | SecureString |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Indicates whether the password expires.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Indicates that the user cannot change the password on the user account.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Type: | SwitchParameter |
Aliases: | wi |
Position: | Named |
Default value: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
System.String, System.DateTime, System.Boolean, System.Security.SecureString
You can pipe a string, a DateTime object, a boolean value, or a secure string to this cmdlet.
Outputs
System.Management.Automation.SecurityAccountsManager.LocalUser
This cmdlet returns a LocalUser object. This object provides information about the user account.
Notes
- A user name cannot be identical to any other user name or group name on the computer. A user name
cannot consist only of periods
.
or spaces. A user name can contain up to 20 uppercase characters or lowercase characters. A user name cannot contain the following characters:
"
, /
, \
, [
, ]
, :
, ;
, |
, =
, ,
, +
, *
, ?
, <
, >
, @
A password can contain up to 127 characters.
The PrincipalSource property is a property on LocalUser, LocalGroup, and LocalPrincipal objects that describes the source of the object. The possible sources are as follows:
- Local
- Active Directory
- Azure Active Directory group
- Microsoft Account
Note
PrincipalSource is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank.