AboutFree templates
How-to · Google Workspace

Bulk create users in Google Workspace from a CSV file

At the end, every user in your CSV file has a Google Workspace account in the right organisational unit with a starting password, and you have the upload report showing anything that failed.

Updated 4 Nov 20268 steps2 official sources
Start hereBack to the playbook
Before you start

What you need before step 1

Applies to: Google Workspace Admin console bulk user upload (Directory > Users > Bulk update users), as documented by Google

Admin roles you need

  • A Google Workspace administrator with the User management privilege (a super administrator has it). Google says a non-super admin cannot modify a super admin account.

Licences

  • Enough Google Workspace licences for the new users. Google says Annual plan customers need the licences before uploading; if licences run out, accounts are added from the top row down until none remain.
  • Google says Business editions allow a maximum of 300 users.

Web portals you will use (nothing to install)

Google Admin consoleWeb portal; nothing to install. Works in any current browser on Windows or macOS.https://admin.google.comOpen

Reference documentation

Google help: Add or update multiple users from a CSV fileReference: every column, limit and error messagehttps://knowledge.workspace.google.com/admin/users/add-or-update-multiple-users-from-a-csv-fileRead

Also have ready

  • The user's domain added and verified in Google Workspace (see Add a domain to Google Workspace).
  • The organisational units you will put users in already created.
  • A spreadsheet program that can save as CSV (Google Sheets, Microsoft Excel, or Numbers on a Mac).
  • A list of users with first name, last name, full email address and a starting password.
  • Check for existing personal (unmanaged) Google Accounts that use your domain before you add users, as Google advises.
Step by step

8 steps

  1. 1

    Open Bulk update users

    Where: Google Admin console (admin.google.com) > Menu > Directory > Users

    Sign in with your administrator account, open Menu (three lines, top left) and go to Directory > Users. Select Bulk update users.

    You should see: A Bulk update users panel with Download blank CSV template, Download User Info In CSV File and Attach CSV file.
  2. 2

    Download the blank template

    Where: Bulk update users panel

    Select Download blank CSV template and save the file. Use this template as is: Google says you cannot add new columns (including custom attributes), and an unknown column name or wrong number of columns stops the upload.

    You should see: A CSV file in your Downloads folder whose first row holds the column headers.
  3. 3

    Fill in the required columns

    Where: Google Sheets, Excel or Numbers on your computer

    Open the template and add one row per user. Fill these required columns:

    • First Name [Required] and Last Name [Required]: up to 60 characters each.
    • Email Address [Required]: the full address, such as chris@contoso.com. If the address already exists, Google updates that account instead of creating one.
    • Password [Required]: see the next step.
    • Org Unit Path [Required]: / for the top-level organisational unit, or a path such as /Sales or /Students/First Grade. Do not include your domain name.

    Leave other columns blank unless you need them. Put double quotation marks around any value that contains a comma, line break or double quote, and separate multiple values in one cell with a comma and no spaces. Do not use reserved user names such as abuse or postmaster.

    You should see: Each user is on its own row with all five required columns filled.
  4. 4

    Set passwords

    Where: Same spreadsheet

    Enter a starting password for each user in Password [Required]. Passwords are case-sensitive and need at least 8 characters by default, or whatever minimum your organisation set. To make users choose their own password, enter TRUE in Change Password at Next Sign-In.

    If you have passwords hashed from another system, put the hash in the Password column and enter MD5, SHA-1 or crypt in the Password Hash Function column (upload only). Google does not send a welcome email with sign-in details to CSV-created users, so send each user their address and starting password securely yourself.

    You should see: Every row has a password that meets your organisation's rules, and TRUE in Change Password at Next Sign-In where you want a reset.
  5. 5

    Save as CSV

    Where: Spreadsheet program: File > Save As (Excel), File > Download > Comma-separated values (Google Sheets), or File > Export To > CSV (Numbers)

    Save the file in CSV format. If any user names use non-ASCII or double-byte characters, save as UTF-8 with BOM. Keep each file to 35 MB and 150,000 users at most; split bigger lists into several files, each with the header row. If you also use the New Licenses column, Google limits the file to 200 users.

    You should see: A .csv file that opens in a text editor with the header row first and one line per user.
  6. 6

    Upload the file

    Where: Google Admin console > Directory > Users > Bulk update users

    Select Bulk update users again, then Attach CSV file, choose your file, and select Upload.

    You should see: The Tasks list opens and shows the upload in progress.
  7. 7

    Check the results

    Where: Google Admin console > Tasks list, and your administrator email inbox

    Watch the task until it finishes. Google emails you a report when processing is complete. If any rows failed, download the log file from the Tasks list, fix those rows, and upload a file with only the corrected users.

    You should see: The task shows as complete and the email report lists the users added. Google says new users can take up to 24 hours to get access to services and appear in the Directory.
  8. 8

    Check licences and organisational units

    Where: Google Admin console > Directory > Users

    Filter or search for a few new users and open them to confirm the organisational unit and licence. Google says automatic licensing takes precedence: in an organisational unit with automatic licensing on, any licence set in the CSV is overridden, and no error appears in the log.

    You should see: Each new user appears with the expected organisational unit and a Google Workspace licence.
From experience

Expert tips

Test with three rows first

Upload a file with two or three test users, check the emailed report and the users' organisational units and licences, then upload the rest. Google says new users can take up to 24 hours to appear in the Directory, so do not re-upload the same file thinking it failed; you will get USER ALREADY EXISTS errors.

Automatic licensing overrides your CSV

Google notes that automatic licensing settings take precedence over the licence in the CSV, and no error appears in the log. If users end up with the wrong edition, check the automatic licensing setting under Billing in the Admin console before editing the file again.

Keep old passwords with hashes

If the old system can export password hashes, put them in the Password column and set Password Hash Function to MD5, SHA-1 or crypt, so users keep their existing password at cutover. Otherwise set Change Password at Next Sign-In to TRUE for temporary passwords.

Save as UTF-8 with BOM for non-English names

Google says to save the CSV as UTF-8 including BOM to upload non-ASCII or double-byte names. Excel's plain CSV option can mangle accented characters; choose CSV UTF-8.

Blank columns do not clear values on update

When updating existing users, Google says an emptied optional column does not remove the existing information. Delete columns you do not want to change, and keep only the email address plus the fields you are updating to avoid accidental changes.

Check it worked

How to confirm it worked

  • In Directory > Users, the user count has grown by the number of rows uploaded and a sample of new users shows the right organisational unit.

  • The upload report email shows no failed rows, or you have re-uploaded the corrected ones.

  • A test user can sign in at https://mail.google.com with the starting password (and is asked to change it if you set TRUE).

Undo

How to reverse it

Rollback:

Removing rows from the CSV or re-uploading does not delete accounts; Google says clearing a user's data in the file does not delete the account. To remove users, go to Directory > Users, tick each user, select More options > Delete selected users, choose whether to transfer data, and select Delete Users. Google says you can restore a deleted account for up to 20 days.

Troubleshooting

Errors you might see

Incorrect file format or unknown column name.

Cause: A header was changed or a column added.

Fix: Download a fresh blank template and copy your data under its exact headers.

Incorrect number of columns in the row nn.

Cause: A value with a comma is not enclosed in double quotes, or a row has extra cells.

Fix: Put double quotes around values containing commas, line breaks or quotes, then save and upload again.

"Email Address [Required]" contains reserved username in row nn.

Cause: The row uses a reserved name such as abuse or postmaster.

Fix: Choose a different user name for that row.

ACTION FAILED: OU INVALID

Cause: The Org Unit Path is wrongly formatted or the organisational unit does not exist.

Fix: Use / or a path such as /Sales, without the domain, and create the organisational unit first.

ACTION FAILED: INSUFFICIENT LICENSES

Cause: You ran out of licences part way through.

Fix: Buy more licences, then upload the remaining users.

USER ALREADY EXISTS

Cause: An account with that address already exists.

Fix: Remove the row, or edit the existing user instead.

FAQ

Questions

Do new users get a welcome email?

No. Google says CSV-created accounts do not get the welcome email with credentials, so send sign-in details yourself.

Can I use the same file to update existing users?

Yes. Select Download User Info In CSV File, edit it and upload it. Values in editable columns replace current values; blank optional columns are left unchanged; enter **** (four asterisks) in Password to keep a user's current password.

How many users can one file hold?

Google allows up to 150,000 users and 35 MB per file, or 200 users if you use the New Licenses column.

Is there a better option for very large or ongoing syncs?

Google suggests Google Cloud Directory Sync (LDAP), the Admin SDK API or a third-party tool for larger or more technical deployments.

Sources

Official sources

Vendors change menus and requirements. Confirm on the source before you rely on a detail. Last checked 4 Nov 2026.

Google Workspace Admin Help: Add or update multiple users from a CSV fileGoogle Workspace Admin Help: Delete or remove a user from your organization