👁 Image
dotenv.net 4.0.2

dotenv.net

👁 Build, Test & Coverage
👁 codecov
👁 NuGet Version

dotenv.net is a lightweight library for loading environment variables from .env files in .NET applications. It keeps sensitive configuration out of source code and supports a range of options to suit different project setups.

Installation

Install via NuGet using any of the following methods:

.NET CLI

dotnet add package dotenv.net

Package Manager Console

Install-Package dotenv.net

PackageReference

<PackageReference Include="dotenv.net" Version="4.x.x"/>

Quick Start

using dotenv.net;

// Load .env from the application directory into the system environment
DotEnv.Load();

// Read variables from .env without modifying the system environment
var envVars = DotEnv.Read();
Console.WriteLine(envVars["DATABASE_URL"]);

By default, both methods look for a .env file in the same directory as the application executable.

Configuration Options

Both Load() and Read() accept a DotEnvOptions instance to customise behaviour.

DotEnv.Load(options: new DotEnvOptions(
 ignoreExceptions: false, // Throw on errors instead of silently failing (default: true)
 envFilePaths: ["./config/.env"], // One or more paths to .env files (default: [".env"])
 encoding: Encoding.UTF8, // File encoding (default: UTF-8)
 trimValues: true, // Strip whitespace from values (default: false)
 overwriteExistingVars: false, // Skip vars already set in the environment (default: true)
 probeForEnv: true, // Search parent directories for a .env file (default: false)
 probeLevelsToSearch: 3, // How many directory levels to ascend when probing (default: 4)
 supportExportSyntax: true // Support `export KEY=VALUE` syntax (default: false)
));

Note: probeForEnv and envFilePaths are mutually exclusive. Setting both will throw an InvalidOperationException.

Loading multiple .env files

DotEnv.Load(options: new DotEnvOptions(
 envFilePaths: ["./config/.env", "./secrets/.env"]
));

When overwriteExistingVars is false, keys from earlier files take precedence over those in later files.

Fluent API

DotEnv.Fluent() returns a DotEnvOptions instance that exposes a chainable builder API, useful when you prefer an explicit, readable configuration style.

Loading variables:

DotEnv.Fluent()
 .WithExceptions()
 .WithEnvFiles("./config/.env")
 .WithTrimValues()
 .WithEncoding(Encoding.UTF8)
 .WithOverwriteExistingVars()
 .WithProbeForEnv(probeLevelsToSearch: 6)
 .WithSupportExportSyntax()
 .Load();

Reading variables without writing to the environment:

var envVars = DotEnv.Fluent()
 .WithoutExceptions()
 .WithEnvFiles() // Defaults to .env
 .WithoutTrimValues()
 .WithEncoding(Encoding.UTF8)
 .WithoutOverwriteExistingVars()
 .WithoutProbeForEnv()
 .WithoutSupportExportSyntax()
 .Read();

Fluent builder methods

Reading Variables

DotEnv.Read() returns an IDictionary<string, string> of the parsed key-value pairs without writing anything to the system environment. This is useful for inspecting values or selectively applying them.

var envVars = DotEnv.Read();

if (envVars.TryGetValue("API_KEY", out var apiKey))
{
 // use apiKey
}

EnvReader Utility

The dotenv.net.Utilities namespace provides EnvReader, a helper class for reading strongly-typed values directly from the system environment (i.e., after calling DotEnv.Load()).

using dotenv.net.Utilities;

var host = EnvReader.GetStringValue("DB_HOST");
var port = EnvReader.GetIntValue("DB_PORT");
var enabled = EnvReader.GetBooleanValue("FEATURE_FLAG");

For non-throwing alternatives, use the TryGet* methods:

if (EnvReader.TryGetIntValue("DB_PORT", out var port))
{
 // port is valid
}

Available methods

Contributing

Contributions are welcome. If you have a bug report, feature request, or improvement in mind, please open an issue or submit a pull request.

To get started:

1. Fork the repository and create a feature branch.
2. Make your changes and ensure existing tests still pass.
3. Add tests for any new behaviour.
4. Open a pull request with a clear description of what was changed and why.

The project targets .NET and uses the standard dotnet CLI toolchain. Run the test suite with:

dotnet test

Contributors

Thanks to everyone who has contributed to dotenv.net:

@bolorundurowb @joliveros @vizeke @merqlove @tracker1 @NaturalWill @texyh @jonlabelle @Gounlaf @DTTerastar @Mondonno @caveman-dick @VijoPlays @bobbyg603

License

dotenv.net is licensed under the MIT License. See the file for details.

Happy Coding! 🚀