Settings and Environment Variables

Warning

The current page still doesn’t have a translation for this language.

But you can help translating it: Contributing.

In many cases your application could need some external settings or configurations, for example secret keys, database credentials, credentials for email services, etc.

Most of these settings are variable (can change), like database URLs. And many could be sensitive, like secrets.

For this reason it’s common to provide them in environment variables that are read by the application.

Environment Variables

Tip

If you already know what “environment variables” are and how to use them, feel free to skip to the next section below.

An environment variable (also known as “env var”) is a variable that lives outside of the Python code, in the operating system, and could be read by your Python code (or by other programs as well).

You can create and use environment variables in the shell, without needing Python:

Windows PowerShell

Settings and Environment Variables - 图1

Settings and Environment Variables - 图2

Read env vars in Python

You could also create environment variables outside of Python, in the terminal (or with any other method), and then read them in Python.

For example you could have a file main.py with:

  1. import os
  3. name = os.getenv("MY_NAME", "World")
  4. print(f"Hello {name} from Python")

Tip

The second argument to os.getenv() is the default value to return.

If not provided, it’s None by default, here we provide "World" as the default value to use.

Then you could call that Python program:

Settings and Environment Variables - 图3

As environment variables can be set outside of the code, but can be read by the code, and don’t have to be stored (committed to git) with the rest of the files, it’s common to use them for configurations or settings.

You can also create an environment variable only for a specific program invocation, that is only available to that program, and only for its duration.

To do that, create it right before the program itself, on the same line:

Settings and Environment Variables - 图4

Tip

You can read more about it at The Twelve-Factor App: Config.

Types and validation

These environment variables can only handle text strings, as they are external to Python and have to be compatible with other programs and the rest of the system (and even with different operating systems, as Linux, Windows, macOS).

That means that any value read in Python from an environment variable will be a str, and any conversion to a different type or validation has to be done in code.

Pydantic Settings

Fortunately, Pydantic provides a great utility to handle these settings coming from environment variables with Pydantic: Settings management.

Create the Settings object

Import BaseSettings from Pydantic and create a sub-class, very much like with a Pydantic model.

The same way as with Pydantic models, you declare class attributes with type annotations, and possibly default values.

You can use all the same validation features and tools you use for Pydantic models, like different data types and additional validations with Field().

  1. from fastapi import FastAPI
  2. from pydantic import BaseSettings
  5. class Settings(BaseSettings):
  6.     app_name: str = "Awesome API"
  7.     admin_email: str
  8.     items_per_user: int = 50
  11. settings = Settings()
  12. app = FastAPI()
  15. @app.get("/info")
  16. async def info():
  17.     return {
  18.         "app_name": settings.app_name,
  19.         "admin_email": settings.admin_email,
  20.         "items_per_user": settings.items_per_user,
  21.     }

Tip

If you want something quick to copy and paste, don’t use this example, use the last one below.

Then, when you create an instance of that Settings class (in this case, in the settings object), Pydantic will read the environment variables in a case-insensitive way, so, an upper-case variable APP_NAME will still be read for the attribute app_name.

Next it will convert and validate the data. So, when you use that settings object, you will have data of the types you declared (e.g. items_per_user will be an int).

Use the settings

Then you can use the new settings object in your application:

  1. from fastapi import FastAPI
  2. from pydantic import BaseSettings
  5. class Settings(BaseSettings):
  6.     app_name: str = "Awesome API"
  7.     admin_email: str
  8.     items_per_user: int = 50
  11. settings = Settings()
  12. app = FastAPI()
  15. @app.get("/info")
  16. async def info():
  17.     return {
  18.         "app_name": settings.app_name,
  19.         "admin_email": settings.admin_email,
  20.         "items_per_user": settings.items_per_user,
  21.     }

Run the server

Next, you would run the server passing the configurations as environment variables, for example you could set an ADMIN_EMAIL and APP_NAME with:

Settings and Environment Variables - 图5

Tip

To set multiple env vars for a single command just separate them with a space, and put them all before the command.

And then the admin_email setting would be set to "deadpool@example.com".

The app_name would be "ChimichangApp".

And the items_per_user would keep its default value of 50.

Settings in another module

You could put those settings in another module file as you saw in Bigger Applications - Multiple Files.

For example, you could have a file config.py with:

  1. from pydantic import BaseSettings
  4. class Settings(BaseSettings):
  5.     app_name: str = "Awesome API"
  6.     admin_email: str
  7.     items_per_user: int = 50
  10. settings = Settings()

And then use it in a file main.py:

  1. from fastapi import FastAPI
  3. from .config import settings
  5. app = FastAPI()
  8. @app.get("/info")
  9. async def info():
  10.     return {
  11.         "app_name": settings.app_name,
  12.         "admin_email": settings.admin_email,
  13.         "items_per_user": settings.items_per_user,
  14.     }

Tip

You would also need a file __init__.py as you saw on Bigger Applications - Multiple Files.

Settings in a dependency

In some occasions it might be useful to provide the settings from a dependency, instead of having a global object with settings that is used everywhere.

This could be especially useful during testing, as it’s very easy to override a dependency with your own custom settings.

The config file

Coming from the previous example, your config.py file could look like:

  1. from pydantic import BaseSettings
  4. class Settings(BaseSettings):
  5.     app_name: str = "Awesome API"
  6.     admin_email: str
  7.     items_per_user: int = 50

Notice that now we don’t create a default instance settings = Settings().

The main app file

Now we create a dependency that returns a new config.Settings().

Python 3.9+Python 3.6+Python 3.6+ non-Annotated

  1. from functools import lru_cache
  2. from typing import Annotated
  4. from fastapi import Depends, FastAPI
  6. from .config import Settings
  8. app = FastAPI()
  11. @lru_cache()
  12. def get_settings():
  13.     return Settings()
  16. @app.get("/info")
  17. async def info(settings: Annotated[Settings, Depends(get_settings)]):
  18.     return {
  19.         "app_name": settings.app_name,
  20.         "admin_email": settings.admin_email,
  21.         "items_per_user": settings.items_per_user,
  22.     }
  1. from functools import lru_cache
  3. from fastapi import Depends, FastAPI
  4. from typing_extensions import Annotated
  6. from .config import Settings
  8. app = FastAPI()
  11. @lru_cache()
  12. def get_settings():
  13.     return Settings()
  16. @app.get("/info")
  17. async def info(settings: Annotated[Settings, Depends(get_settings)]):
  18.     return {
  19.         "app_name": settings.app_name,
  20.         "admin_email": settings.admin_email,
  21.         "items_per_user": settings.items_per_user,
  22.     }

Tip

Prefer to use the Annotated version if possible.

  1. from functools import lru_cache
  3. from fastapi import Depends, FastAPI
  5. from .config import Settings
  7. app = FastAPI()
  10. @lru_cache()
  11. def get_settings():
  12.     return Settings()
  15. @app.get("/info")
  16. async def info(settings: Settings = Depends(get_settings)):
  17.     return {
  18.         "app_name": settings.app_name,
  19.         "admin_email": settings.admin_email,
  20.         "items_per_user": settings.items_per_user,
  21.     }

Tip

We’ll discuss the @lru_cache() in a bit.

For now you can assume get_settings() is a normal function.

And then we can require it from the path operation function as a dependency and use it anywhere we need it.

Python 3.9+Python 3.6+Python 3.6+ non-Annotated

  1. from functools import lru_cache
  2. from typing import Annotated
  4. from fastapi import Depends, FastAPI
  6. from .config import Settings
  8. app = FastAPI()
  11. @lru_cache()
  12. def get_settings():
  13.     return Settings()
  16. @app.get("/info")
  17. async def info(settings: Annotated[Settings, Depends(get_settings)]):
  18.     return {
  19.         "app_name": settings.app_name,
  20.         "admin_email": settings.admin_email,
  21.         "items_per_user": settings.items_per_user,
  22.     }
  1. from functools import lru_cache
  3. from fastapi import Depends, FastAPI
  4. from typing_extensions import Annotated
  6. from .config import Settings
  8. app = FastAPI()
  11. @lru_cache()
  12. def get_settings():
  13.     return Settings()
  16. @app.get("/info")
  17. async def info(settings: Annotated[Settings, Depends(get_settings)]):
  18.     return {
  19.         "app_name": settings.app_name,
  20.         "admin_email": settings.admin_email,
  21.         "items_per_user": settings.items_per_user,
  22.     }

Tip

Prefer to use the Annotated version if possible.

  1. from functools import lru_cache
  3. from fastapi import Depends, FastAPI
  5. from .config import Settings
  7. app = FastAPI()
  10. @lru_cache()
  11. def get_settings():
  12.     return Settings()
  15. @app.get("/info")
  16. async def info(settings: Settings = Depends(get_settings)):
  17.     return {
  18.         "app_name": settings.app_name,
  19.         "admin_email": settings.admin_email,
  20.         "items_per_user": settings.items_per_user,
  21.     }

Settings and testing

Then it would be very easy to provide a different settings object during testing by creating a dependency override for get_settings:

  1. from fastapi.testclient import TestClient
  3. from .config import Settings
  4. from .main import app, get_settings
  6. client = TestClient(app)
  9. def get_settings_override():
  10.     return Settings(admin_email="testing_admin@example.com")
  13. app.dependency_overrides[get_settings] = get_settings_override
  16. def test_app():
  17.     response = client.get("/info")
  18.     data = response.json()
  19.     assert data == {
  20.         "app_name": "Awesome API",
  21.         "admin_email": "testing_admin@example.com",
  22.         "items_per_user": 50,
  23.     }

In the dependency override we set a new value for the admin_email when creating the new Settings object, and then we return that new object.

Then we can test that it is used.

Reading a .env file

If you have many settings that possibly change a lot, maybe in different environments, it might be useful to put them on a file and then read them from it as if they were environment variables.

This practice is common enough that it has a name, these environment variables are commonly placed in a file .env, and the file is called a “dotenv”.

Tip

A file starting with a dot (.) is a hidden file in Unix-like systems, like Linux and macOS.

But a dotenv file doesn’t really have to have that exact filename.

Pydantic has support for reading from these types of files using an external library. You can read more at Pydantic Settings: Dotenv (.env) support.

Tip

For this to work, you need to pip install python-dotenv.

The .env file

You could have a .env file with:

  1. ADMIN_EMAIL="deadpool@example.com"
  2. APP_NAME="ChimichangApp"

Read settings from .env

And then update your config.py with:

  1. from pydantic import BaseSettings
  4. class Settings(BaseSettings):
  5.     app_name: str = "Awesome API"
  6.     admin_email: str
  7.     items_per_user: int = 50
  9.     class Config:
  10.         env_file = ".env"

Here we create a class Config inside of your Pydantic Settings class, and set the env_file to the filename with the dotenv file we want to use.

Tip

The Config class is used just for Pydantic configuration. You can read more at Pydantic Model Config

Creating the Settings only once with lru_cache

Reading a file from disk is normally a costly (slow) operation, so you probably want to do it only once and then re-use the same settings object, instead of reading it for each request.

But every time we do:

  1. Settings()

a new Settings object would be created, and at creation it would read the .env file again.

If the dependency function was just like:

  1. def get_settings():
  2.     return Settings()

we would create that object for each request, and we would be reading the .env file for each request. ⚠️

But as we are using the @lru_cache() decorator on top, the Settings object will be created only once, the first time it’s called. ✔️

Python 3.9+Python 3.6+Python 3.6+ non-Annotated

  1. from functools import lru_cache
  3. from fastapi import Depends, FastAPI
  4. from typing_extensions import Annotated
  6. from . import config
  8. app = FastAPI()
  11. @lru_cache()
  12. def get_settings():
  13.     return config.Settings()
  16. @app.get("/info")
  17. async def info(settings: Annotated[config.Settings, Depends(get_settings)]):
  18.     return {
  19.         "app_name": settings.app_name,
  20.         "admin_email": settings.admin_email,
  21.         "items_per_user": settings.items_per_user,
  22.     }
  1. from functools import lru_cache
  2. from typing import Annotated
  4. from fastapi import Depends, FastAPI
  6. from . import config
  8. app = FastAPI()
  11. @lru_cache()
  12. def get_settings():
  13.     return config.Settings()
  16. @app.get("/info")
  17. async def info(settings: Annotated[config.Settings, Depends(get_settings)]):
  18.     return {
  19.         "app_name": settings.app_name,
  20.         "admin_email": settings.admin_email,
  21.         "items_per_user": settings.items_per_user,
  22.     }

Tip

Prefer to use the Annotated version if possible.

  1. from functools import lru_cache
  3. from fastapi import Depends, FastAPI
  5. from . import config
  7. app = FastAPI()
  10. @lru_cache()
  11. def get_settings():
  12.     return config.Settings()
  15. @app.get("/info")
  16. async def info(settings: config.Settings = Depends(get_settings)):
  17.     return {
  18.         "app_name": settings.app_name,
  19.         "admin_email": settings.admin_email,
  20.         "items_per_user": settings.items_per_user,
  21.     }

Then for any subsequent calls of get_settings() in the dependencies for the next requests, instead of executing the internal code of get_settings() and creating a new Settings object, it will return the same object that was returned on the first call, again and again.

lru_cache Technical Details

@lru_cache() modifies the function it decorates to return the same value that was returned the first time, instead of computing it again, executing the code of the function every time.

So, the function below it will be executed once for each combination of arguments. And then the values returned by each of those combinations of arguments will be used again and again whenever the function is called with exactly the same combination of arguments.

For example, if you have a function:

  1. @lru_cache()
  2. def say_hi(name: str, salutation: str = "Ms."):
  3.     return f"Hello {salutation} {name}"

your program could execute like this:

  1. sequenceDiagram
  3. participant code as Code
  4. participant function as say_hi()
  5. participant execute as Execute function
  7.     rect rgba(0, 255, 0, .1)
  8.         code ->> function: say_hi(name="Camila")
  9.         function ->> execute: execute function code
  10.         execute ->> code: return the result
  11.     end
  13.     rect rgba(0, 255, 255, .1)
  14.         code ->> function: say_hi(name="Camila")
  15.         function ->> code: return stored result
  16.     end
  18.     rect rgba(0, 255, 0, .1)
  19.         code ->> function: say_hi(name="Rick")
  20.         function ->> execute: execute function code
  21.         execute ->> code: return the result
  22.     end
  24.     rect rgba(0, 255, 0, .1)
  25.         code ->> function: say_hi(name="Rick", salutation="Mr.")
  26.         function ->> execute: execute function code
  27.         execute ->> code: return the result
  28.     end
  30.     rect rgba(0, 255, 255, .1)
  31.         code ->> function: say_hi(name="Rick")
  32.         function ->> code: return stored result
  33.     end
  35.     rect rgba(0, 255, 255, .1)
  36.         code ->> function: say_hi(name="Camila")
  37.         function ->> code: return stored result
  38.     end

In the case of our dependency get_settings(), the function doesn’t even take any arguments, so it always returns the same value.

That way, it behaves almost as if it was just a global variable. But as it uses a dependency function, then we can override it easily for testing.

@lru_cache() is part of functools which is part of Python’s standard library, you can read more about it in the Python docs for @lru_cache().

Recap

You can use Pydantic Settings to handle the settings or configurations for your application, with all the power of Pydantic models.

  • By using a dependency you can simplify testing.
  • You can use .env files with it.
  • Using @lru_cache() lets you avoid reading the dotenv file again and again for each request, while allowing you to override it during testing.