# What is a .env file?

> A .env file is a plain-text list of KEY=VALUE lines that a library or runtime loads into environment variables. How the format works and where it breaks.

URL: https://crunu.com/learn/dotenv-file
Language: en
Updated: 2026-10-30

A `.env` file is a plain-text file of `KEY=VALUE` lines, kept next to an application, that a library or the runtime reads at startup and turns into [environment variables](https://crunu.com/learn/environment-variable) for that one process.

## Where the format comes from

No standard defines it. The convention spread through the dotenv libraries: the Node.js package describes itself as "a zero-dependency module that loads environment variables from a `.env` file into process.env" ([dotenv README](https://github.com/motdotla/dotenv)), and most languages have a port. Frameworks such as Next.js, Vite and Laravel read `.env` files on their own, and Node.js has done it natively since version 20.6.0 with `node --env-file=.env` ([Node.js CLI docs](https://nodejs.org/api/cli.html)).

A typical file looks like this:

```dotenv
# payments-api, local development
DATABASE_URL=postgres://localhost:5432/payments
STRIPE_SECRET_KEY=sk_test_EXAMPLE_not_a_real_key
LOG_LEVEL=debug
```

## Why the details matter

Every parser is its own implementation, so one file can mean slightly different things to different tools:

- **Comments.** In dotenv, a `#` starts a comment unless the value is quoted. A password that contains `#` gets cut short without quotes.
- **Variables that already exist.** dotenv says it "will never modify any environment variables that have already been set", and Node.js gives the value from the environment precedence over the file. A stale `export` in your shell silently wins.
- **References.** [Next.js](https://nextjs.org/docs/app/guides/environment-variables) expands `$OTHER_VAR` inside `.env` files, so a literal `$` must be escaped. The dotenv package itself leaves that to add-ons.
- **Multiline values.** Recent dotenv and Node.js versions accept them; older or simpler parsers don't.

So "works on my machine" can be a parsing difference rather than a different value.

## Common mistakes

- **Committing it.** Laravel's documentation is typical: the `.env` file "should not be committed to your application's source control", because a repository leak would expose every credential in it ([Laravel](https://laravel.com/docs/13.x/configuration)). Adding the file to `.gitignore` after a commit doesn't help either: "Files already tracked by Git are not affected" ([gitignore](https://git-scm.com/docs/gitignore)).
- **Shipping it.** A `COPY . .` in a Dockerfile or a build artifact that includes the project root carries the file along.
- **Passing it around.** A `.env` sent in chat becomes a copy nobody can revoke. The team version of this problem has its own guide: [how to share .env files with your team](https://crunu.com/guides/share-env-files-with-a-team).
- **One file for every stage.** Copying production values into the file you use for local work puts them on every laptop that runs the app.

## How Crunu handles .env files

An environment in Crunu holds files: `.env` files, INI files such as `~/.aws/credentials`, flat YAML and plain text. Values are encrypted on your device, and the server stores only ciphertext. The editor shows a `.env` file as a table of names and hidden values, and keeps the latest 100 versions.

You don't need the file on disk to use it. `crunu run` passes the variables of files marked **Load as environment variables (crunu run)** to the program it starts, so the project directory can stay free of real values:

```sh
crunu run --env payments-api/development -- npm run dev
```

When a tool insists on a file, `crunu pull` writes it with mode 0600. Crunu doesn't change how your framework parses `.env` files; the quirks above still apply to files you write out. For checking a file before you use it, see the [.env linter](https://crunu.com/tools/env-linter), and for the question of committing, [should you commit .env files](https://crunu.com/blog/should-you-commit-env-files).

## Sources

- [dotenv README](https://github.com/motdotla/dotenv), checked October 30, 2026.
- [Node.js command-line options: --env-file](https://nodejs.org/api/cli.html), checked October 30, 2026.
- [Laravel 13.x: Configuration](https://laravel.com/docs/13.x/configuration), checked October 30, 2026.
- [Git documentation: gitignore](https://git-scm.com/docs/gitignore), checked October 30, 2026.
- [Next.js: How to use environment variables](https://nextjs.org/docs/app/guides/environment-variables), checked October 30, 2026.