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
-AccountExpires
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 |
-AccountNeverExpires
Indicates that the account does not expire.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-Confirm
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 |
-Description
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 |
-Disabled
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 |
-FullName
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 |
-Name
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 |
-NoPassword
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 |
-Password
Specifies a password for the user account. You can use Read-Host -AsSecureString
, 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 |
-PasswordNeverExpires
Indicates whether the password expires.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-UserMayNotChangePassword
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 |
-WhatIf
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
You can pipe a string to this cmdlet.
You can pipe a DateTime object to this cmdlet.
You can pipe a boolean value to this cmdlet.
You can pipe a secure string to this cmdlet.
Outputs
System.Management.Automation.SecurityAccountsManager.LocalUser
This cmdlet returns a LocalUser object representing the created 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.
Related Links
Feedback
Submit and view feedback for