compareBy Aliniyaz Mamat · updated

dotenv vs Doppler: when to upgrade from .env files

dotenv vs Doppler: dotenv is a free library that loads a .env file from each developer's machine; Doppler is a hosted secrets manager that stores secrets centrally and injects them into local runs, CI and deployments. The switch makes sense when passing .env files around becomes a risk or a chore.

Key takeaways

  • ✓dotenv: no account, no server, five minutes of setup. Secrets are shared by hand (password manager, encrypted file).
  • ✓Doppler: one dashboard for all environments, per-user access, audit log, sync to Vercel, GitHub Actions, Kubernetes and clouds.
  • ✓Your code doesn't change: doppler run -- node server.js fills process.env just like dotenv.
  • ✓Typical trigger to switch: 3+ people need production secrets, a compliance audit trail, or several platforms that must stay in sync.
  • ✓Open-source and self-hostable alternative: Infisical. Enterprise: HashiCorp Vault. Cloud-native: AWS/GCP/Azure secret stores.

dotenv vs Doppler side by side

dotenvDoppler
Typeopen-source libraryhosted secrets manager (SaaS)
Costfreefree tier, paid team plans (check current pricing)
Setupminutesan hour or so for the first project
Where secrets livefiles on each machineDoppler's encrypted store
Access controlfile system permissionsper user, project and environment
Audit lognoyes
CI/CD and host syncmanual copyintegrations
Works offlineyeswith a cached fallback file
Self-hostingn/ano

What changes in your workflow

# dotenv: each developer has a .env, the app loads it
node server.js                       # with import "dotenv/config"

# Doppler: secrets come from the CLI, no file on disk
doppler login
doppler setup                        # choose project + config (dev, stg, prd)
doppler run -- node server.js        # process.env is filled before start

Because both end in process.env, application code stays identical. Validation and types are a separate layer either way, see dotenv vs config libraries.

When dotenv is enough

  • Solo projects or two people who share secrets through a password manager.
  • Open-source projects whose .env only holds local development values.
  • One deployment target whose dashboard is the production source of truth.

Keep it safe with the basics: .env best practices, a committed .env.example, and encrypted sharing with the ENV encrypt tool instead of plain text in chat.

When to move to a secrets manager

  • Three or more engineers need production or staging secrets.
  • An auditor asks who accessed which secret and when.
  • Several platforms (Vercel, a worker host, GitHub Actions) must receive the same values.
  • A secret has leaked before, or offboarding someone means rotating everything by hand.
  • Onboarding includes "ask someone to send you the .env".

Alternatives to Doppler

ToolModelFits when
Infisicalopen source, self-hostable or cloudyou want data sovereignty or no vendor lock-in
HashiCorp Vault / OpenBaoself-hosted, very flexiblea platform team can run it; dynamic database credentials
AWS Secrets Manager / Parameter Storecloud-nativeyou are mostly on AWS
Google Secret Manager / Azure Key Vaultcloud-nativeyou are on GCP / Azure
1Password Secrets Automationpassword-manager basedthe team already uses 1Password

A broader comparison: HashiCorp Vault alternatives and dotenv vs secrets managers.

Migrating from dotenv to Doppler

  1. Clean the file first: remove duplicates with the ENV cleaner and check for leaked keys with the ENV leak checker.
  2. Create a project and upload: doppler secrets upload .env (once per config: dev, stg, prd).
  3. Replace start commands with doppler run -- … locally and in scripts.
  4. Connect the integrations for your hosts and CI so values sync automatically.
  5. Delete the local .env files and rotate anything that was ever shared in plain text.

Frequently asked questions

Do I have to change my code to use Doppler?

No. doppler run -- <command> injects secrets as environment variables, so code that reads process.env.DATABASE_URL keeps working unchanged.

What if Doppler is down when my app starts?

doppler run can use a local encrypted fallback file with the last known secrets. For production, many teams sync secrets into the platform's own environment settings so startup doesn't depend on Doppler at all.

Is switching back possible?

Yes. doppler secrets download --no-file --format env > .env exports everything as a regular .env file.

Is Doppler better than a password manager for secrets?

For application secrets, yes: it injects values into processes and CI and keeps per-environment configs. A password manager is fine for small teams sharing a few values by hand.

Do I still need .env.example with Doppler?

It's still useful as documentation of which keys exist, especially for open-source contributors who won't have Doppler access.

Related tools

Continue reading