How to Create and Use a .env File for Your Projects

What a .env file does and why you need one

A .env file is a plain text file that stores sensitive information your code needs to run — things like database passwords, API keys, and secret tokens. Instead of writing these values directly into your code, you store them in .env and your program reads them when it starts. This keeps secrets out of version control systems like GitHub, where they could be exposed if your code is public.

The .env file lives in your project's root folder (the main directory) and stays on your computer or server only. When you push your code to GitHub or share it with others, the .env file never goes with it — only the code that reads from it does. This is the standard practice across web development, whether you're building with Node.js, Python, Ruby, or other languages.

Key Takeaways

A .env file stores passwords, API keys, and other secrets in plain text on your machine, separate from your code.
You create it by opening a text editor, typing your variables in KEY=VALUE format, and saving it as .env with no file extension.
Your code reads .env values using a library like dotenv (Node.js), python-dotenv (Python), or similar tools for your language.
Always add .env to your .gitignore file so it never gets uploaded to GitHub or other version control systems.
Different machines can have different .env files — one for development, one for production — without changing your code.

Creating a .env file on Windows, Mac, or Linux

Open any text editor — Notepad on Windows, TextEdit on Mac, or nano/vim on Linux. Type your variables in the format KEY=VALUE, one per line. For example:

DATABASE_PASSWORD=mySecurePassword123 API_KEY=abc123def456 DATABASE_URL=postgres://user:pass@localhost:5432/mydb PORT=3000

Save the file in your project's root folder (the main directory where your code files live) and name it exactly .env — no other extension, just a dot followed by env. On Windows and Mac, your text editor will save it correctly. On Linux, use nano .env or vim .env in the terminal, type your variables, then press Ctrl+X (nano) or Esc then :wq (vim) to save.

The file will be hidden on Mac and Linux because it starts with a dot. To see it, use ls -la in the terminal on Mac or Linux, or enable "Show hidden files" in Windows Explorer. This is normal — the file is there, just not visible by default.

Reading .env values in your code

Your code cannot read .env automatically. You need a library that loads the file when your program starts. For Node.js, install the dotenv package with npm install dotenv, then add this at the very top of your main file:

require('dotenv').config(); const dbPassword = process.env.DATABASE_PASSWORD;

For Python, install python-dotenv with pip install python-dotenv, then add this at the top of your file:

from dotenv import load_dotenv import os load_dotenv() db_password = os.getenv('DATABASE_PASSWORD')

For other languages like Ruby, PHP, or Go, search for "[your language] dotenv" to find the equivalent library. The pattern is always the same: load the .env file, then access variables by their key name. Your code never sees the actual values until runtime — they stay hidden in the file.

Preventing .env from being uploaded to version control

Create or edit a file named .gitignore in your project root (the same folder where .env lives). Add the line .env on its own line. This tells Git to ignore the .env file and never upload it to GitHub, GitLab, or any other repository.

If you already pushed .env to GitHub before adding it to .gitignore, you need to remove it from Git's history. Run git rm --cached .env to stop tracking it, then commit that change. The file stays on your machine but will no longer be uploaded in future pushes. For security, treat any secrets that were in the uploaded .env as compromised — change those passwords and regenerate those API keys immediately.

Using different .env files for different environments

You often need different settings for development (on your computer), testing, and production (the live server). Create separate .env files: .env.development, .env.test, and .env.production. Your code can load the right one based on an environment variable.

In Node.js, add this at the top of your main file:

require('dotenv').config({ path: `.env.${process.env.NODE_ENV}` });

Then set NODE_ENV to development, test, or production before running your code. On your development machine, you might have a .env.development file with a local database password. On the production server, you'd have a .env.production file with the real database password. Neither file is in version control — each machine maintains its own.

Common mistakes and how to avoid them

Do not put quotes around values unless the value itself contains spaces or special characters. API_KEY=abc123 is correct; API_KEY="abc123" will include the quotes as part of the value. If your value has spaces, use quotes: DATABASE_URL="postgres://user:pass@localhost/my db".

Do not commit .env to version control, even once. If you do, assume the secrets are exposed and change them. Do not name it .env.example or .env.sample and fill it with real secrets — these files are often committed by mistake. If you want to show teammates what variables they need, create a .env.example file with placeholder values like API_KEY=your_api_key_here, and commit that instead.

Do not use spaces around the equals sign. API_KEY = abc123 will not work; use API_KEY=abc123. Do not add comments on the same line as a variable — put comments on their own line starting with #.

Frequently Asked Questions

What if I forgot to add .env to .gitignore before pushing to GitHub?

Run git rm --cached .env to stop tracking it, then commit and push. The file stays on your machine but won't be uploaded in future pushes. However, the secrets are already in GitHub's history. Change those passwords and regenerate those API keys immediately, as anyone with access to the repository can see them.

Can I use .env on a production server?

Yes, but many production environments use other methods. Some hosting platforms (Heroku, AWS, Vercel) let you set environment variables through their dashboard instead of uploading a .env file. Check your host's documentation. If you do use .env on a server, make sure the file has restricted permissions so only your application can read it.

Why does my code not see the .env values?

Make sure you loaded the dotenv library at the very top of your main file, before any code that reads from process.env or os.getenv(). If you load it after other code runs, those variables won't exist yet. Also check that your .env file is in the project root, not in a subfolder, and that the variable names in your code match exactly — KEY and key are different.

Should I commit .env.example to version control?

Yes. Create a .env.example file with the same keys as your .env but with placeholder values like DATABASE_PASSWORD=your_password_here. Commit this to show teammates what variables they need to set. They copy it to .env, fill in their own values, and never commit .env itself.

What if my .env file has special characters in a value?

Wrap the value in double quotes: DATABASE_PASSWORD="p@ssw0rd!#$%". If the value contains a double quote, escape it with a backslash: API_KEY="abc\"123". For most cases, quotes are optional — only use them when the value has spaces or special characters.

This guide is for general information only and is not medical, financial, legal, or other professional advice. For decisions specific to your situation, consult a qualified professional. See our Editorial Policy.