environs is a Python library (current version 15.0.1) designed for simplified parsing of environment variables, aligning with the Twelve-Factor App methodology for separating configuration from code. It provides robust type-casting, validation, and flexible parsing of various data types including lists, dictionaries, dates, and URLs. It also integrates seamlessly with `.env` files. environs is actively maintained and has a steady release cadence.
pip install environsVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize `environs`, read various environment variables with type-casting, provide default values, and parse URLs. It shows how `environs` helps manage different data types from string-based environment variables. For local development with `.env` files, ensure `python-dotenv` is installed and `env.read_env()` is called.
Use the `Env` instance directly as a callable, e.g., `env('VAR_NAME')` for required variables or `env('VAR_NAME', default='fallback')` for optional variables with a default.Ensure `pip install python-dotenv` is run and place `env.read_env()` at the beginning of your configuration loading logic.
Always use the `env` object provided by `environs` (e.g., `env('VAR_NAME')`, `env.int('NUMBER')`) throughout your application for configuration values to ensure consistency and proper type-casting. Avoid directly accessing `os.environ` for `environs`-managed values after initialization.If a string URL is needed, use `from environs import Env, validate; url_string = env.str('MY_URL', validate=validate.URL())`. When providing a `default` value to `env.url()`, it must also be a `urllib.parse.ParseResult` object.Always call `env.seal()` after parsing all your required and optional environment variables if you are using validation, particularly with deferred (non-eager) validation.
Ensure the correct package is installed in your active virtual environment. If you intend to use `environs`, run `pip install environs`. If you are working with Django and specifically intend `django-environ`, run `pip install django-environ`. Verify your active Python interpreter if using multiple environments.
Uninstall the incorrect `environ` package (`pip uninstall environ`) and then install the correct `environs` library (`pip install environs`). Make sure your import statement is `from environs import Env` or `import environs` followed by `env = environs.Env()`.
Ensure the environment variable is actually set where your application runs, or provide a default value when calling `env()` (e.g., `MY_VAR = env('MY_VAR', 'default_value')`). Confirm that `env.read_env()` is called before accessing variables and that your `.env` file is correctly located (usually in the project root) or its path is explicitly provided to `read_env()`.Call `env.read_env()` early in your application's startup. Ensure the `.env` file is located in the current working directory of your script or provide its explicit path to `env.read_env(path='/path/to/.env')`. If you want `.env` values to override system variables, pass `override=True` to `read_env()` (e.g., `env.read_env(override=True)`).