Add or update multiple users from a CSV file

Before people on your team can sign in and use your organization's Google services (for example, Google Workspace or Cloud Identity), they need a user account. If you have many new users, you can add their accounts all at once from a CSV file.

You can also update multiple existing accounts from a spreadsheet, or CSV file.

Expand all  |  Collapse all

Before you begin

Make sure this is the right option

• If you need to upload a large amount of users, you can use a CSV file. If you’re assigning or updating new licenses using the New Licenses [Upload Only] column, the limit is 200 users. If not, the limit is 150,000 users. For details on the New Licenses [Upload Only] column, go to Column reference.
• However, if you have an LDAP server, such as Microsoft Active Directory, or have programming skills, we recommend other options for larger organizations. For details, go to Options for adding users.

Understand account licensing and billing

• (Annual Plan customers) Make sure you have enough licenses—Before you add users, you might need to add new licenses to your account. Learn how to get more licenses.
• (Flexible Plan customers) Your subscription cost depends on how many users you have—Adding user accounts increases your monthly payment.
• (Google Workspace Business edition customers) You can add a maximum of 300 users. There is no minimum or maximum user limit for Enterprise plans.
• Automatic licensing takes precedence—If you add a user to an organizational unit that has automatic licensing turned on, the automatic licensing settings take precedence over the license you assign to the user in the CSV file. An error won't be shown in the log file.

Check for unmanaged and visitor accounts

• Unmanaged accounts—Check to see if anyone you plan to add already has a Google Account. Then follow steps to avoid conflicts with those accounts. Go to Find and add unmanaged users.
• Visitor accounts—If users invite people outside your organization who don't have Google accounts to collaborate on Drive, they'll receive visitor accounts, in the format visitor'[e-mail]. If you add a user with the same username as a visitor account, the account will be converted to a full Google Workspace account. The account will keep its current Drive file permissions. Learn more about sharing documents with visitors.

Known issues

There’s a known License Management issue that can occur when you are updating multiple users with a CSV file. For details, see Google Workspace Known Issues.

To complete these steps, you need the appropriate User management privilege. Without this privilege, you won't see all the controls needed to complete these steps.

Add users from a CSV file

If you use a CSV file to create new accounts, the users do not receive a new user welcome email with their credentials. You have to send your new users their account credentials separately.

Tip: If you forget the new user's password, reset the password and then email the new one to the user.

Step 1: Download the template file

1. Sign in to your Google Admin console.

   Sign in using your administrator account (does not end in @gmail.com).

2. In the Admin console, go to Menu  DirectoryUsers.
3. At the top of the page, click Bulk update users.

   

4. Click Download blank CSV template to download a comma-separated values (.csv) file.
5. Open the CSV file in a spreadsheet application, such as Google Sheets or Microsoft Excel.

   The file has columns for the attributes that can appear in each user's profile. Profiles appear in the Admin console and in the users' Contacts Manager.

Step 2: Enter users' information

1. For each user you want to add, enter the following required information in these columns in the CSV file:
   • First Name
   • Last Name
   • Email Address—Use the format [e-mail]
   • Password—Must be at least 8 characters.

   • Org Unit Path—Enter / (forward slash) to place users in your top-level organizational unit. You might do this if you haven't set up an organizational hierarchy in the Admin console. Or, you can enter the path for a specific organizational unit, staring with a forward slash, such as /Sales.

     For column descriptions and formatting details, review the guidelines below.

     Your CSV file should look like something like this:

     

2. (Optional) To require a user to reset their password when first signing in, in the Change Password at Next Sign-In column, enter TRUE. Otherwise, leave the column empty.
3. (Optional) To specify additional information, such as recovery emails, home addresses, or licenses, enter it in the remaining columns.

Step 3: Save the file

After it's complete, save it as a CSV file (.csv).

Notes:

• Maximum CSV file size is 35 MB.
• Maximum number of records per file is 150,000.

  If your file is larger or has too many records, open it in your spreadsheet program, split the table into separate files, and save each one as a CSV file. Make sure you include the column headings row in all CSV files.

• To upload non-ASCII or double byte usernames, first save the CSV file in UTF-8, including BOM.

Step 4: Upload the file

1. At the top of the Users page, click Bulk update users.
2. Click Attach CSV file.
3. Browse to the location on your computer and attach the CSV file.
4. Click Upload. If there's an error, enter the missing information in your CSV file and upload it again. For more information, go to Resolve common errors below.

   Your Tasks list opens automatically and shows the progress of the upload. Once processing is complete, you'll receive an email report.

   If there's a processing error, download the log file from your Tasks list. For more information, go to Resolve common errors below.

It can take up to 24 hours for new users to have access to Google services and appear in the Directory. Learn more about the Directory.

Follow CSV file format guidelines

General guidelines

If you want to...	Follow these guidelines...
Enter multiple values in a column	For multiple values in a single column, such as phone numbers and email addresses, separate them with a comma (but no spaces)—for example: [e-mail],[e-mail]
Enter values that include commas, with line breaks, or double quotes	Enclose the values in double quotation marks—for example, "123 Anystreet, Anytown"
Upload non-ASCII or double byte usernames	Be sure to save the CSV file in UTF-8 so the usernames are readable.
Add more columns	You can enter information only in the columns available in the downloaded file. You can't add new columns, such as those for custom attributes.
Upload existing users	If you enter the email address or email alias of an existing user in the Email Address column, the existing user's account will be updated with any changes you make to their information in the other columns.

Column reference

Required columns

Column	Description/Format
First Name / Last Name	A first name and last name can each have up to 60 characters.
Email Address	The user's sign-in name. Enter the full email address: [e-mail]
Password	Passwords are case sensitive. By default, a password must have at least 8 characters. You can change password requirements for your organization. If you're updating existing users and you don't want to change their passwords, enter **** (4 asterisks). If a Password Hash Function is also specified, the Password column must contain the hashed password. For example, if you use SHA-1 and the hash of password abc is xyz, enter xyz in the Password column.
Org Unit Path	For placing users in an organizational unit. If you haven't yet set up an organizational hierarchy: Enter / (forward slash) only to place all users in the top-level parent organizational unit. You can move users to other organizational units you create later. If you've already set up an organizational hierarchy: Use the format in the following examples to place each user in an organizational unit—in either your top-level parent organizational unit or a child organizational unit below it. Examples: / (for the top-level parent–don't enter your domain name) /Sales (for a child below the top-level parent) /Students/First Grade

Optional columns

Column	Format
Password Hash Function [Upload Only]	Specify one of the following supported hash functions: MD5, SHA-1, or crypt. The Password column must contain the hashed password. For example, if you use SHA-1 and the hash of password abc is xyz, enter xyz in the Password column. Tip: You can find utilities on the web to generate hashed passwords using the supported hash functions.
Recovery Email and Recovery Phone	For providing recovery information used for login challenges. Recovery email—An email address outside of your domain. Recovery phone—Must be in the E.164 format. They must start with the plus sign (+), followed by the country code, area code, and phone number. Entries can have a maximum of 15 digits. Example: [phone]. Note: Recovery phone should be unique for each user. If the same recovery phone number is used by multiple users, that number is automatically blocked for security reasons. Employee ID—Some login challenges ask users to enter their employee ID. The ID can contain numbers, letters, and symbols. For details, go to Add employee ID as a login challenge.
Work/Home Address	If you include commas or line breaks in an address, enclose the address in double quotation marks—for example, "123 Anystreet, Anytown"
New Primary Email [Upload Only]	For editing existing user accounts only. Specify a new primary email address (username).
Building ID, Floor Name, and Floor Section	To enter this information, follow these guidelines.
Change Password at Next Sign-In	To require a user to change their password the next time they sign in to their account, enter TRUE. Otherwise, leave the column empty or enter FALSE.
New Status [Upload Only]	For editing existing user accounts only. To archive or suspend a user, enter Archived or Suspended. To unarchive or restore a suspended user, enter Active.
New Licenses [Upload Only]	For editing existing user accounts only. To assign a different license to a user, enter the SKU ID for the license. Separate multiple license IDs with commas—for example: 1010020020,1010330002 A CSV file can include up to 200 users that are being assigned a new license.

Resolve common errors

Errors when you upload your CSV file

Error	Cause/Solution
File is empty	Your file doesn't contain any information.
Incorrect file format or unknown column name	The columns in your file should be titled First Name [Required], Last Name [Required], Email Address [Required], Password [Required], and Org Unit Path [Required].
File must have the "column name" column	A required column is missing.
Empty "column name" in row nn	A column that requires information is empty in a specific row. For example, you'll see the error Empty "Org Unit Path [Required]" in row 2 if you didn't enter the organizational unit in which you want to place a user's account. Go to Org Unit Path above.
File is too large to upload	The CSV file is over 35 MB or there are more than 150,000 records in the file. Open the file and split the table into separate files. Save each one as a CSV file. Make sure you include the column headings row in all CSV files.
Incorrect number of columns in the row nn	A column is missing for a specific row.
"Email Address [Required]" contains reserved username in row nn	Certain accounts are reserved and can't be created—for example, abuse and postmaster.
Action_Failed: User_LIMIT_EXCEEDED	You reached the limit to add licenses to your Google Workspace edition, so some users in your CSV file did not get a license. Note: Starting from the top row of your CSV file, Google Accounts are added until no more licenses are available.

Errors in the log file

Error	Cause/Solution
ACTION FAILED: Validation	An entry contains unsupported characters. For help, go to Username and group name guidelines.
ACTION FAILED: UNKNOWN ERROR	Most likely, a temporary error occurred. Try uploading the CSV file again, or uploading items in smaller batches. This error can also occur if you've entered an incorrect domain name in a user's email address (after the @ sign) in the Email Address column.
ACTION FAILED: INSUFFICIENT LICENSES	Your organization's Google Account doesn't have enough licenses for all the new users in your CSV file. Accounts are added starting from the top row until there are no more licenses available. You can purchase more licenses and then upload the remaining users in the CSV file.
ACTION FAILED: OU INVALID	This error usually means one of the following formatting errors: The Org Unit Path column isn't formatted correctly. One or more organizational units you entered don't exist in the Admin console. Make sure the organizational unit names match those in your organizational hierarchy in the Admin console.
ACTION FAILED: USER NAME INVALID	The email address (username) in the Email Address column isn't formatted correctly. Make sure you enter the user's full email address. Also check for spaces in the address.
ACTION FAILED: PERMISSION DENIED	The user's email address in the Email Address column includes a domain name (after the @ symbol) that's not associated with your organization's Google Account. Make sure you entered the domain name in the email address correctly.
ACTION FAILED: PASSWORD INVALID	User password incorrect. Can occur if you’re trying to update an account that was deleted. Verify you’re using the correct password for each user.
ACTION FAILED: PASSWORD HASH FUNCTION INVALID	The Password Hash Function column contains an incorrect hash function name.
ACTION FAILED: UPDATE USER LICENSES FAILED	One or more SKU IDs in the New License column couldn't be updated for the user. Ensure that the SKU IDs are correct and the column is formatted correctly for multiple SKU IDs.
ACTION FAILED: ONLY VFE ALLOWED	The user currently has a Vault Former Employee (VFE) license, but the New License column contains a SKU ID for a license other than the VFE. You can't add another license type to a user with a VFE license.
ACTION FAILED: UNASSIGNABLE LICENSE	The New License column contains a SKU ID for a product for which you don't have a subscription.
ACTION FAILED: MULTIPLE LICENSES IN SAME PRODUCT	The upload failed for one of the following reasons: The New License column contains an SKU ID that has the same Product ID as the currently assigned license. For example, if you change a license from Business Starter to Enterprise Plus, the CSV file upload will fail, because those two edition names have the same Product ID, Google-Apps. For details, see Google Product and SKU IDs. The New License column contains multiple SKU IDs with the same Product ID assigned to the same user.
ACTION FAILED: REPEATED SKU ASSIGNMENTS FOR USER	The New License column contains the same SKU ID 2 or more times.
ACTION FAILED: SKU SWITCH RESTRICTED	The New License column contains a SKU ID for a product that your current subscription doesn't let you upgrade or downgrade to.
ACTION FAILED: UPDATING DELETED USER	The New License column contains a SKU ID, but the user account is deleted.

If you add a user to an organizational unit that has automatic licensing turned on, the automatic licensing settings take precedence over the license you assign to the user in the CSV file. An error won't be shown in the log file.

Update existing user accounts

Edit accounts with a CSV file

You can save time when you need to edit multiple accounts by downloading a list of accounts from the Admin console.

Before you begin

• Any information in columns you can edit replaces existing information in the Admin console when you upload the file.
• For columns you don't want to change, you can either delete them (if the column isn't required), leave their information in the file, or delete their information.
• If you delete all information from a column that's not required, but leave the column in the CSV file, the existing information is not removed from the user's account when you upload the file.
• If you don't want to change a user's password, make sure the Password column contains the symbols **** (4 asterisks).
• If you don't want to edit a specific user's information, you can leave their row in the CSV file or remove it. If you remove all of a user's information in the file, their account is not deleted.
• To change a user's username, enter the new email address in the New Primary Email column.
• If you've changed the primary domain for your Google Workspace account, go to Rename user addresses in bulk after changing your primary domain for specific instructions.

To edit several user accounts

1. Sign in to your Google Admin console.

   Sign in using your administrator account (does not end in @gmail.com).

2. In the Admin console, go to Menu  DirectoryUsers.
3. At the top of the page, click Bulk update users.

   

4. Click Download User Info In CSV File to download a comma-separated values (.csv) file with all user accounts.

   Your Tasks list opens automatically and shows the progress of the download.

5. Under Your Tasks, click Download CSV.
6. Open the CSV file in a spreadsheet application, such as Google Sheets or Microsoft Excel.

   The file has columns for the attributes in each user's profile.

7. Edit the information in the file.
8. After you've filled in the spreadsheet, save it as a CSV file.
9. At the top of the Users page, click Bulk update users.
10. Click Attach CSV file.
11. Browse to the location on your computer and attach the CSV file.
12. Click Upload.
13. If there's an error, enter the missing information in your CSV file and upload it again. For more information, go to Resolve common errors.

    Your Tasks list opens automatically and shows the progress of the upload. Once processing is complete, you'll receive an email report.

14. If there's a processing error, download the log file from your Tasks list. For more information, go to Resolve common errors.

Sync user data with your LDAP server

If you have an LDAP server, such as Microsoft Active Directory, you can use Google Cloud Directory Sync to synchronize your Google users, groups, and shared contacts to match the information in your LDAP server.

Want someone to do this for you? Get professional help with setup.

Related articles

• Reset a user’s password
• Set up password recovery for users
• Individually add user accounts

 

_{Google, Google Workspace, and related marks and logos are trademarks of Google LLC. All other company and product names are trademarks of the companies with which they are associated.}