In this article, I will explain my simple function New-LocalLinuxUser for PowerShell Core 6 that acts as a wrapper and allows you to create a local Linux user with PowerShell.

With the general release of PowerShell Core 6.0, users now have the ability to use the previously strictly Windows-based scripting language on Linux and macOS. This is quite a great achievement from the PowerShell team. It not only enables IT pros to manage Windows from other operating systems but also lets them use PowerShell for Linux and macOS IT administration tasks.

Here, I am going to show how you can create Linux users with PowerShell. The idea was to try to port the Windows PowerShell cmdlet New-LocalUser to Linux. Now obviously, Linux creates local users differently than Windows, but the idea is essentially similar.

How does Linux create local users? ^

Before we write our function, let's look at the command that creates Linux users: useradd. When comparing useradd with New-LocalUser, I attempted to find similar parameters I could use. Below is a table of these:

-NameNo named parameter, but you can specify one after useradd

You could certainly use other parameters with useradd, but I will work with these to make things simple.

An example of using useradd in Linux would be something like this:

In the example above, the username is "testuser." Notice we use the format YYYY-MM-DD for the expiredate parameter. It's a requirement to work with this format, so we'll use a string in our function.

New-LocalLinuxUser code ^

Now that we see how useradd works, we can go over the simple PowerShell Core wrapper function New-LocalLinuxUser.

Here is the code for the New-LocalLinuxUser function:

To hide the password used at the -Password parameter in the shell, I used the PSCredential type. You will see I use the GetNetworkCredential method to draw out the password used within the function. To set the password, you'll have to use the Get-Credential cmdlet along with the New-LocalLinuxUser command. Of course we only need the password from the credential, so I'll show how to do that below.

In addition, you'll notice in the function I use the passwd command to change the password after creating the account. This is the standard Linux command to change a user's password.

Using New-LocalLinuxUser ^

In this example, I have a user "Dan," the expiration date "2019-12-01," a password, and the description for the account, which will be "Standard account."

Running New LocalLinuxUser

Running New LocalLinuxUser

I specify -UserName dan in Get-Credential, so there is no prompt to input in the username. Since we are ultimately just using the password, it doesn't matter what the username actually is.

After running the command, running the command id dan shows the user's creation. By default, the user receives the user identifier (UID) and group identifier (GID) 1003.

Conclusion ^

Creating and using the New-LocalLinuxUser function is a good example of how you can use PowerShell Core to create wrappers around Linux commands to make using Linux similar to Windows. I imagine the PowerShell community will begin creating modules that can do similar tasks like this one to extend the capabilities of PowerShell Core better.

Join the 4sysops PowerShell group!

Your question was not answered? Ask in the forum!

  1. Harashita 1 year ago


    I have installed Powershell in rhel 7. I want to create local user using powershell. I am getting below error.

    PS /opt/microsoft/powershell/6/Modules> New-LocalUser "azureadmin" -Password $Password -FullName "AZURE USER" -Description "Description of this account."
    New-LocalUser : The term 'New-LocalUser' is not recognized as the name of a cmdlet, function, script file, or operable program.
    Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
    At line:1 char:1
    + New-LocalUser "azureadmin" -Password $Password -FullName "AZURE USER" ...
    + ~~~~~~~~~~~~~
    + CategoryInfo : ObjectNotFound: (New-LocalUser:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException



  2. Harashita:

    The function is New-LocalLinuxUser, not New-LocalUser :-), and you would need to be sure to dot source it..

    I'd suggest not making the description mandatory (I don't think Linux requires it? it has been a while), and I'd make the password expiration either be a string or a datetime object, and then you could output it in the correct format..  I reworked this.. (not tested.. but it should be ok..)

    The biggest changes I made:

    1. ValidateScript to force the user name to match the Linux rules for user accounts as far as I understand them. (Thanks google 😉
      If someone has a case-insensitive
    2. Added parametersetnames to allow a string for the user expiration date or a datetime object.
    3. I changed the $Password parameter to a SecureString
    4. I added a $Credential parameter to use a pscredential object
    5. Modified all the parameters to accept pipeline input.. This could be modified further to accept multiple accounts for a bulk creation, or even a CSV input.
    6. if both the $Password & $Credential parameters are null, it throws an error.  (I don't know of way to make both of them mandatory without creating a ridiculous number of parameter sets to cover every situation)
    7. If the expiration date is sent in as a string, it does a datetime parse test against it to validate it really is a date, and then creates a string out of it with the right format.
    8. If the expiratiopn date is sent as datetime object, I create the same string in the right format.
    9. Modified the output errors to include the $LastExitCode
    10. Made the comment ($Description) optional

    David F.


  3. It occurs to me I didn't "fix" the password piece..

    This will mean that if the user put in both a $Password and $Credential, the $Credential would be overridden..

    David F.


Leave a reply

Your email address will not be published. Required fields are marked *


© 4sysops 2006 - 2020


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account