Get the free coreGet core

What is a .env file and why it should never be committed

Updated 5 min readSection 05 / Threats
SHORT ANSWER

A .env file is a plain text file of settings, one NAME=value pair per line, in the root of your project. A library such as dotenv loads those values into the environment of your app. It usually holds secrets, so you do not commit it. Commit a copy with fake values called .env.example instead.

If you cloned a repository and found a .env in it, here is what it is. Your app needs settings that change between machines: a database address, a port, an API key. Instead of writing them into the code, you put them in one small file next to the code. That is an env file.

01What an env file contains

The name stands for environment. Every program runs with a set of named values called environment variables, which the operating system hands to the program when it starts. Reading the values from a file is a convenient way to fill that set. dotenv is a zero-dependency module that loads environment variables from a .env file into process.env. process.env is the place where a JavaScript program reads its environment variables. The approach comes from the Twelve-Factor App, a recipe for keeping config apart from code.

Twelve-Factor gives a test for config that lives outside the code. Could the codebase be made open source at any moment without compromising any credentials? A separate .env that stays out of the repository is one way to pass it.

Here is an example of the file. The values are fake:

DATABASE_URL=postgres://localhost:5432/myapp
PORT=3000
OPENAI_API_KEY=sk-replace-with-your-real-key

The usual setup is one .env per environment, for instance .env for development and .env.production for production. Each machine then gets its own copy with its own values. Read the example line by line. The first is an address your app connects to, the second is a port number, and the third is a secret, an API key. If you are new to keys, what an API key is explains the last line.

02How to create it and load it

Create a file named .env in the root of your project. Put one NAME=value pair on each line and save it. The file is plain text, so any code editor opens it: open the project folder and find .env in the file list.

Writing the file does nothing by itself, because your app has to load it. In a JavaScript project that is the job of dotenv. Install it with npm install dotenv --save, then load the file as early as possible in your app:

require('dotenv').config()
// or import 'dotenv/config' // for esm

After that line, process.env.OPENAI_API_KEY holds the value from the file.

03Why you should never commit it

The file is where your secrets live, and Git remembers every commit. A secret that lands in a commit stays in the history even after you delete the file. Anyone who can clone the repository can read it there. Should you commit it? No, unless you encrypt the file with dotenvx. An encrypted .env can sit in source control; a plain one with real keys cannot.

Environment variables themselves are unlikely to be checked into the code repo accidentally. Unlikely still leaves a chance, which is why the next step matters.

04Keep it out of Git with .gitignore

.gitignore is a file that tells Git which files to skip. Add .env to it before your first commit. GitHub's Node template ignores .env and .env.* but keeps .env.example. The exact lines, and what to do when the file is already tracked, are on the page about where to store API keys.

05.env.example: share the shape, not the secrets

A teammate who clones your project needs to know which variables to set. That is the job of .env.example: the same names as your .env, with fake or empty values. It is safe to commit, and GitHub's template keeps it out of the ignore list. To make one, copy your .env, replace every real value with a fake or empty one, and save the copy as .env.example. A new teammate copies it back to .env and fills in their own values.

FileReal secrets?Commit it?
.envYesNo
.env.exampleNo, fake or empty valuesYes, the template keeps it
.env encrypted with dotenvxEncryptedIt can sit in source control

06What if it was already pushed

Treat every secret in it as compromised and revoke it with its provider first. Deleting the file in the next commit does not change that. If the repository is public, speed matters: automated scanners can locate publicly exposed secrets in minutes, and malicious actors can exploit them within hours. The next steps are on these pages:

07A file on disk is readable by more than you

The file is plain text, so other programs on your Mac can read it too, not only your app. The s1ngularity payload searched for wallets, keystores, .env files and SSH keys on Linux and macOS. AI coding tools work in the same folder as the file, so see keeping a Claude Code env file away from the agent.

A secrets manager can load values without a plaintext file on disk; 1Password does it with op run. Even then, processes on your computer can read the environment of other processes run by the same user.

08The short version

An env file is a small text file of settings for one machine. Keep the real one out of Git, commit a .env.example with fake values, and revoke any key that was ever pushed. If you want a next step, set up the .gitignore line now, before the first commit.

FAQ

What is a .env file?

A text file of settings that dotenv and similar libraries load into the environment of your app. It usually holds secrets such as API keys, so it is not committed.

How do I create a .env file?

Create a file named .env in the root of your project and write one NAME=value pair per line. Add it to .gitignore before your first commit.

How do I open a .env file?

It sits in the root of the project and is plain text, so any code editor opens it. Open the project folder in the editor and find it in the file list.

What do I do with a .env file?

Keep real values in it on your own machine, keep it out of Git, and commit a copy with fake values named .env.example instead.

What happens if we push a .env file?

Treat every secret in it as compromised and revoke the keys first. The steps are on the page about a leaked key.

Is it ever fine to commit a .env file?

Only if it is encrypted. The answer is no unless you encrypt it with dotenvx, a tool that encrypts the file with dotenvx encrypt -f .env.

Sources

  1. dotenv README
  2. Twelve-Factor App, config
  3. GitHub gitignore, Node template
  4. GitHub docs, remediating a leaked secret
  5. 1Password docs, secrets in environment variables
  6. Wiz, s1ngularity supply chain attack
Your .env file lives on the Mac where your agents work. Artificial Immunity watches program starts there and reports what it finds.Get the free core