Dotenv Linter

0.7.0 · active · verified Fri Apr 17

dotenv-linter is a command-line utility for linting `.env` files, ensuring they adhere to best practices and common standards. It helps prevent syntax errors, enforce naming conventions, and identify issues like duplicate keys or incorrect line endings. The current version is `0.7.0`, with releases typically driven by new features, Python version support updates, and dependency upgrades.

Common errors

```
dotenv-linter: command not found
```
cause The `dotenv-linter` executable is not in your system's PATH, or the package was not installed correctly in the active environment.

fix Ensure `pip install dotenv-linter` completed successfully. If using a virtual environment, activate it. Check your PATH configuration.
```
D001: Found `\r\n` (CRLF) as line ending
```
cause Your `.env` file contains Windows-style CRLF line endings, which are forbidden since version 0.6.0.

fix Convert your `.env` file to use LF (Unix-style) line endings. You can often do this in your text editor (e.g., VS Code: 'CRLF' in status bar -> 'LF'), or using `sed -i 's/\r$//' .env` on Linux/macOS.
```
Error: The provided argument is not a file or directory.
```
cause The path provided to `dotenv-linter` (e.g., `.env`) does not exist or is inaccessible.

fix Double-check the filename and path. Ensure the file exists in the current directory or provide the correct absolute/relative path. Also, verify file permissions.
```
D002: Found duplicate key `YOUR_KEY`
```
cause Your `.env` file contains the same environment variable key defined more than once.

fix Remove duplicate definitions of the key. Environment variables should typically be defined only once per `.env` file. The last definition often overrides previous ones, but this behavior can be inconsistent across systems.

Warnings

breaking Older Python versions are regularly dropped. v0.6.0 dropped Python 3.9, v0.5.0 dropped 3.7 and 3.8, and v0.4.0 dropped 3.6. Ensure your environment uses Python 3.10 or newer.
Fix: Upgrade your Python interpreter to 3.10 or later. Check `requires_python` in PyPI for the exact range.
breaking The linter now explicitly forbids `\r\n` (CRLF) line endings in `.env` files, enforcing `\n` (LF). Files with CRLF will raise a `D001` linting error.
Fix: Convert your `.env` files to use LF line endings. Most text editors can do this automatically. For example, in Git, ensure `core.autocrlf` is configured appropriately.
gotcha The internal grammar parser switched from `ply` to `lark` in version 0.7.0. While this is largely an internal change, it might subtly alter parsing behavior for highly malformed or edge-case `.env` files.
Fix: If encountering unexpected parsing issues after upgrading to 0.7.0, review your `.env` files for any non-standard syntax. The new parser might be stricter or interpret edge cases differently.

Install

pip install dotenv-linter Install latest version

Quickstart

This quickstart demonstrates how to create a simple `.env` file and then lint it using the `dotenv-linter` command-line tool. It also shows an example with a duplicate key to illustrate how the linter identifies common issues.

echo 'APP_ENV=development
DATABASE_URL=postgres://localhost:5432/db
# This is a comment
' > .env
dotenv-linter .env

# Example with an error (duplicate key)
echo 'FOO=bar
FOO=baz' > .env_with_error
dotenv-linter .env_with_error

view raw JSON →