What's New
Upgrade Guide
The Basics
The Craft Command
Architectural Concepts
Useful Features
Orator ORM
Managers and Drivers
Official Packages
Masonite Essentials
How-to Guides



Environments in Masonite are defined in .env files and contain all your secret environment variables that should not be pushed into source control. You can have multiple environment files that are loaded when the server first starts. We'll walk through how to configure your environment variables in this documentation.

Never load any of your .env files into source control. .env and .env.* are in the .gitignore file by default so you should not worry about accidentally pushing these files into source control.

Getting Started

Masonite comes with a LoadEnvironment class that is called in the bootstrap/ file. This file in imported into the file which is where the execution of the environment actually happens because of the import.

You likely won't have to use this class since this class handles most use cases by default but we will go over how the class itself works.

In bootstrap/ you will see a code that looks something like:

from masonite.environment import LoadEnvironment

This class instantiation does a few things:

The first thing is it loads the .env file located in the base of your application into the Python environment. If you installed Masonite using craft install then Masonite automatically create this .env file for you based on the .env-example file. If you have installed Masonite but do not see this .env file then you can create it manually and copy and paste the contents of .env-example.

The next thing it will do is look for an APP_ENV variable inside your .env file it just loaded and then look for an environment with that value.

For example, this variable:


Will load additionally load the .env.local environment file.

This may be useful to have more global environment variables that can be shared across your team like Stripe, Mailgun, or application keys and then have more developer specific values like database connections, Mailtrap or different storage drivers for development.

Loading Additional Environments

In addition to loading the .env file and the additional environment file defined in your .env file, you can load a third environment by specifying it in the constructor:

from masonite.environment import LoadEnvironment

This will load the .env file, the .env.local file and the .env.development environment file.

Loading Only A Single Environment

If you don't want to load an additional environment and instead want to load only 1 single environment then you can pass in the only parameter.

from masonite.environment import LoadEnvironment

This will load only the .env.development environment file.

Getting Environment Variables

Environment variables should be set on a project per project basis inside your .env file. When the server starts, it will load all of those environment variables into the current global environment. You can fetch these environment variables 1 of 2 ways:


You can obviously get them in the normal Python way by doing something like:

import os
os.getenv('DB_PORT') #== '5432' (string)

Notice that the above example is a string. We typically need the data type to be casted to the respective type. For example we need 5432 to be an integer and need True to be a boolean.


We can use the env() function in order to accomplish this which takes the place of os.getenv(). This looks like:

from masonite import env
env('DB_PORT', 'default') #== 5432 (int)

If the value is a numeric then it will cast it to an integer. Below are the examples of what this function will cast:


Casts to (type)


5432 (int)


True (bool)


True (bool)


False (bool)


False (bool)


smtp (string)

If you do not wish to cast the value then pass in false as the third parameter:

from masonite import env
env('DB_PORT', 'default', cast=False) #== '5432' (string)