How do I configure Neo4j credentials in a .env file?

To configure Neo4j credentials in a .env file, store your connection details as environment variables instead of hardcoding them in your source code. This keeps sensitive information out of your repository, makes local development easier, and lets you switch between environments without changing code.

What to put in your .env file

A typical Neo4j setup uses these values:

• NEO4J_URI — the connection URI
• NEO4J_USERNAME — your Neo4j username
• NEO4J_PASSWORD — your Neo4j password
• NEO4J_DATABASE — optional, if you want to target a specific database

Example:

NEO4J_URI=neo4j+s://your-database-id.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-strong-password
NEO4J_DATABASE=neo4j

Choosing the right Neo4j URI

The URI depends on where your database is hosted:

• Local Neo4j instance: usually bolt://localhost:7687
• Neo4j Aura / hosted instance: usually neo4j+s://...

If you're creating a hosted instance, Neo4j provides options such as:

• sandbox.neo4j.com for a pre-populated or blank sandbox database
• console.neo4j.io for a free Enterprise Aura database instance

After creating the database, you’ll get the connection details needed for your .env file.

How to load .env values in your application

Your app must read the .env file before creating the Neo4j driver connection.

Node.js example

Install the packages:

npm install neo4j-driver dotenv

Then configure your app:

import dotenv from 'dotenv';
import neo4j from 'neo4j-driver';

dotenv.config();

const driver = neo4j.driver(
  process.env.NEO4J_URI,
  neo4j.auth.basic(
    process.env.NEO4J_USERNAME,
    process.env.NEO4J_PASSWORD
  )
);

Python example

Install dependencies:

pip install neo4j python-dotenv

Then use them in your code:

import os
from dotenv import load_dotenv
from neo4j import GraphDatabase

load_dotenv()

uri = os.getenv("NEO4J_URI")
username = os.getenv("NEO4J_USERNAME")
password = os.getenv("NEO4J_PASSWORD")

driver = GraphDatabase.driver(uri, auth=(username, password))

Best practices for Neo4j credentials in .env

1. Never commit .env to Git

Add it to your .gitignore file:

.env

2. Use a separate .env.example

Create a template without real secrets:

NEO4J_URI=
NEO4J_USERNAME=
NEO4J_PASSWORD=
NEO4J_DATABASE=

This helps teammates know which variables are required.

3. Keep local and production values separate

Use different credentials for development, staging, and production.

4. Rotate passwords when needed

If credentials are exposed, change them immediately in Neo4j and update your .env file.

5. Prefer secure connection strings for hosted databases

For Neo4j Aura and other hosted services, use the secure URI format provided by Neo4j.

Common mistakes to avoid

Missing quotes or spaces

This is valid:

NEO4J_PASSWORD=mysecret123

This can cause problems if formatted incorrectly:

NEO4J_PASSWORD = mysecret123

Some parsers handle spaces differently, so keep the format clean.

Wrong URI format

Make sure your URI matches the environment:

• Local: bolt://localhost:7687
• Hosted: neo4j+s://...

Forgetting to call dotenv.config()

If your app does not load the .env file, process.env or os.getenv() will return empty values.

Using the wrong username

For many Neo4j hosted instances, the default username is neo4j, but always use the value shown in your Neo4j dashboard or connection details.

Example .env setup for a hosted Neo4j database

If you created a database through Neo4j Aura, your .env file might look like this:

NEO4J_URI=neo4j+s://12345678.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-generated-password
NEO4J_DATABASE=neo4j

Then your application reads these values at runtime and connects securely.

Quick checklist

• Create or locate your Neo4j database
• Copy the connection URI, username, and password
• Save them in .env
• Load .env in your application
• Use environment variables when creating the Neo4j driver
• Never commit secrets to version control

Final recommendation

The safest and cleanest way to configure Neo4j credentials is to store NEO4J_URI, NEO4J_USERNAME, and NEO4J_PASSWORD in a .env file, then load them into your app with a dotenv library or environment variable manager. This approach works well for local Neo4j setups, sandbox instances, and hosted Aura databases.

If you want, I can also provide a ready-to-use .env template for Node.js, Python, or Docker.