Migrate to Clerk
Move your users to Clerk from the platform you use today, and keep their passwords when your platform exports them. The Clerk CLI exports your users, checks each one against your Clerk instance before it writes anything, and imports them. If something goes wrong, it can undo the import.
Supported platforms
- Auth0
- Auth.js (NextAuth)
- Better Auth
- Firebase
- Supabase
- WorkOS
- Another Clerk instance, such as development to production. A production instance starts empty.
- AWS Cognito, which uses a password migrator instead of
clerk migrate. - Another platform, by writing a source that maps its export onto Clerk's user schema.
Better Auth, Firebase, and Supabase exports keep password hashes, so most of those users sign in with the passwords they already have. Auth0 releases hashes only through a support request. Auth.js and WorkOS users, and users copied with clerk migrate export clerk, reset their password or sign in another way. Each guide lists the exceptions.
Choose an approach
Most migrations import every user at once, which is what clerk migrate does. A trickle migration moves them over time while both systems run, and you build that import yourself with the Backend API. Plan your migration covers the trade-offs of each, and how your app keeps referencing users by the IDs they had before.
Requirements
Install the Clerk CLI, sign in, and link the project directory you'll run the migration from to the Clerk application you're importing into:
npm install -g clerk
clerk auth login
clerk linkTo skip clerk auth login and clerk link, set CLERK_SECRET_KEY to the of the instance you're importing into, or pass it with --secret-key.
To skip the global install, replace clerk with npx clerk@latest in each command. To update an existing install, run clerk update.
import and undo target the linked application's development instance by default. Pass --instance prod or a full instance ID to choose another. With a Secret Key, the key picks the instance, so pass the production instance's key to import into production. For other ways to pick the instance and Secret Key, see choose the destination instance.
The CLI stores each run in .clerk/migrate/<run_id>/ and adds .clerk/ to .gitignore. To store runs elsewhere, see command behavior.
Run your migration
If you work with an AI coding agent, the clerk-migrate skill can run your migration for you with the Clerk CLI. Install Clerk's skills:
npx skills add clerk/skillsThen ask your agent to migrate your users to Clerk. The skill exports your users, runs a dry run against your instance, and shows you what it found. It imports only after you approve.
To run the migration yourself, export your users, check them against your instance, then import them:
clerk migrate export <platform> # prints a run ID
clerk migrate import <export_run_id> --dry-run # checks, writes nothing
clerk migrate import <export_run_id> --yes # importsIf you exported your users another way, skip clerk migrate export and pass the file to clerk migrate import with --source.
Each platform's guide walks through these steps and lists what comes across and what doesn't, such as social sign-ins. For the checks, re-runs, undo, and exit codes, see How the CLI migrates users. Run clerk migrate <command> --help to see all options.
Foreign keys
Keep referencing your users by the IDs they had before the migration.
How the CLI migrates users
Learn how the CLI checks users, continues an interrupted import, and undoes one.
Account linking
Learn how Clerk links a social sign-in to an imported user.
Feedback
Last updated on