Env::Dot(3pm)

💖 Env::Dot 💖

okay bestie, welcome to Env::Dot, from the User Contributed Perl Documentation family. she reads your environment variables straight out of a .env file and honestly? she's that girl. 👑

---

✨ NAME ✨

Env::Dot — reads environment variables from a .env file. yes that's it, that's the whole thing, and it's iconic. 🎀

✨ VERSION ✨

this is version 0.022 💅

✨ SYNOPSIS ✨

bestie. the synopsis is literally empty. nothing there. the void. 🫥

do not panic tho — all the juicy usage examples are living their best life down in STATUS. go look there. ⭐

✨ DESCRIPTION ✨

she gives you more flexibility in how you manage and use your .env file. that's the whole vibe. 🌸

✨ STATUS ✨

heads up, queen: this module is currently being developed, so changes in the API are possible — though, like, not likely. 🙈

# If your dotenv file is `.env`:
use Env::Dot;
# or
use Env::Dot 'read';

print $ENV{'VAR_DEFINED_IN_DOTENV_FILE'};

# If you have a dotenv file in a different filepath:
use Env::Dot read => {
    dotenv_file => '/other/path/my_environment.env',
};

# When you absolutely require `.env` file:
use Env::Dot read => {
    required => 1,
};

Attn. ⚠️ Existing environment variables always take precedence to dotenv variables! a dotenv variable (a variable from a file) does not overwrite an existing environment variable. this is by design — because a dotenv file is there to augment the environment, not to replace it. periodt.

which means you can override a variable in a .env file by creating its counterpart in the environment. for instance:

unset VAR
echo "VAR='Good value'" >> .env
perl -e 'use Env::Dot; print "VAR:$ENV{VAR}\n";'
# VAR:Good value
VAR='Better value'; export VAR
perl -e 'use Env::Dot; print "VAR:$ENV{VAR}\n";'
# VAR:Better value

🌈 Features 🌈

• If no .env file is present, then do nothing — by default, Env::Dot will do nothing if there is no .env file. you can also configure Env::Dot to break execution if there is no .env file in the current working directory. no cap. 💀

use Env::Dot read => {
    required => 1,
};

• Specify other dotenv files with path — if your .env file is located in another path, not the current working directory, you can use the environment variable ENVDOT_FILEPATHS to tell where your dotenv file is located. you can specify several file paths; just separate them by :. 🔥

Env::Dot will load the files in the reverse order, starting from the last. this is the same ordering as used in PATH variable: the first overrules the following ones — that is, when reading from the last path to the first path, if the same variable is present in more than one file, the later one replaces the one already read.

Attn. if you are using Windows, separate the paths by ;! 🪟

for example, if you have the following directory structure:

project-root
| .env
+ - sub-project
  | .env

and you specify ENVDOT_FILEPATHS=project-root/sub-project/.env:project-root/.env, then the variables in file project-root/.env will get replaced by the more specific variables in project-root/sub-project/.env.

in Windows, this would be ENVDOT_FILEPATHS=project-root\sub-project\.env;project-root\.env

N.B. The ordering has changed in version 0.0.9. 📌

• Support different types of .env files — Unix Shell source command compatible dotenv files use double or single quotation marks (" or ') to define a variable which has spaces. but, for instance, Docker compatible .env files do not use quotation marks. the variable's value begins with the = sign and ends with linefeed.

you can specify in the dotenv file itself — by using meta commands — which type of file it is. 💅

• Use executable envdot to bring the variables into your shell — the executable is distributed together with the Env::Dot package. it is in the directory script. ✨

The executable script/envdot is not Windows compatible!

a Windows (MS Command and Powershell compatible) version, script\envdot.bat, is possible in a future release. please contact the author if you are interested in it. 🫶

eval "$(envdot)"

N.B. if your .env file(s) contain variables which need interpolating — for example, to combine their value from other variables or execute a command to produce their value — you have to use the envdot program. Env::Dot does not do any interpolating. it cannot, because that would involve running the variable in the shell context. 😭

🦋 DotEnv File Meta Commands 🦋

the var: commands affect only the subsequent variable definition. if there is another envdot command, the second overwrites the first and default values are applied again. 💜

• read:from_parent — by setting this option to true, Env::Dot or envdot command will search for .env files in the file system tree upwards. it will load the first .env file it finds from the current directory upwards to root. ⬆️

using read:from_parent will only find and read one .env file in a parent directory. if you want to chain the .env files, they all must set read:from_parent — except the top one.

this functionality can be useful in situations where you have parallel projects which share common environment variables in one .env file in a parent directory. 🗂️

if there is no parent .env file, Env::Dot will break execution and give an error. 😵

by default this setting is off.

• read:allow_missing_parent — when using option read:from_parent, if the parent .env file does not exist, by default Env::Dot will emit an error and break execution. in some situations, it might be normal that a parent .env file could be missing. turn on option read:allow_missing_parent if you do not want an error in that case. 🙏

by default this setting is off.

• file:type — changes how Env::Dot reads lines below from this command. default is:

# envdot (file:type=shell)
VAR="value"

other possible value of file:type is:

# envdot (file:type=plain)
VAR=My var value

• var:allow_interpolate — by default, when writing variable definitions for the shell, every variable is treated as static and surrounded with single quotation marks ' in Unix shell which means shell will read the variable content as is. by setting this to 1 or true, you allow shell to interpolate. this meta command is only useful when running envdot command to create variable definitions for eval command to read. ⭐

# envdot (var:allow_interpolate)
DYNAMIC_VAR="$(pwd)/${ANOTHER_VAR}"

✨ DEPENDENCIES ✨

No external dependencies outside Perl's standard distribution. she's low maintenance, we love that for her. 💖

✨ FUNCTIONS ✨

No functions exported to the calling namespace. clean. minimal. no clutter. 👑

🌸 load_vars 🌸

loads variables from .env file or files in environment variable ENVDOT_FILEPATHS.

✨ SEE ALSO ✨

• Env::Assert will verify that you certainly have those environmental variables you need. it also has an executable which can, for example, perform the check in the beginning of a docker container run. 🐳
• Dotenv and ENV::Util <https://metacpan.org/pod/ENV::Util> are packages which also implement functionality to use .env files in Perl.
• Config::ENV and Config::Layered::Source::ENV provide other means to configure application with the help of environment variables. 🛠️
• shdotenv <https://github.com/ko1nksm/shdotenv> is a project to provide dotenv for shells with support for POSIX-compliant and multiple .env file syntax. 🐚

✨ AUTHOR ✨

Mikko Koivunalho <mikkoi@cpan.org> 💌

✨ COPYRIGHT AND LICENSE ✨

this software is copyright (c) 2023 by Mikko Koivunalho.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🫶

---

okay that's the whole page bestie, you ate that. 💅 this was Env::Dot version 0.022, running on perl v5.40.1, and this page is dated 2026-05-09. go forth and dotenv, queen. 🌈✨👑