{"id":9724,"library":"env-tools","title":"Env Tools","description":"Tools for using .env files in Python. This library simplifies loading environment variables from `.env` files and accessing them with optional type casting and default values. As of version 2.4.0, it offers a stable API for managing application configurations, with minor releases for improvements and bug fixes.","status":"active","version":"2.4.0","language":"en","source_language":"en","source_url":"https://github.com/beaugunderson/python-env-tools","tags":["environment-variables","dot-env","configuration","settings"],"install":[{"cmd":"pip install env-tools","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"load_env","correct":"from env_tools import load_env"},{"symbol":"get_env","correct":"from env_tools import get_env"},{"symbol":"EnvNotFoundError","correct":"from env_tools import EnvNotFoundError"}],"quickstart":{"code":"import os\nfrom env_tools import load_env, get_env, EnvNotFoundError\n\n# --- Example .env file content (assume this is in a file named .env) ---\n# MY_APP_DEBUG=True\n# DATABASE_URL=postgresql://user:pass@host:5432/db\n# API_KEY=abc-123-xyz\n# WORKERS=4\n# ----------------------------------------------------------------------\n\n# Load environment variables from the .env file in the current directory.\n# By default, load_env doesn't raise an error if the .env file is missing.\n# Set critical=True to make file loading mandatory.\nload_env()\n\n# Access environment variables with optional type casting and defaults\ndebug_mode = get_env(\"MY_APP_DEBUG\", cast_to_type=bool, default=False)\ndb_url = get_env(\"DATABASE_URL\")\napi_key = get_env(\"API_KEY\", default=\"default_api_key_if_not_set\")\nworkers = get_env(\"WORKERS\", cast_to_type=int) # No default, will raise EnvNotFoundError if missing\n\nprint(f\"Debug Mode: {debug_mode} (Type: {type(debug_mode)})\")\nprint(f\"Database URL: {db_url}\")\nprint(f\"API Key: {api_key}\")\nprint(f\"Workers: {workers} (Type: {type(workers)})\")\n\n# Demonstrating a missing variable without a default\ntry:\n    get_env(\"UNDEFINED_VAR_NO_DEFAULT\")\nexcept EnvNotFoundError as e:\n    print(f\"\\nCaught expected error for missing variable: {e}\")\n\n# OS environment variables take precedence over .env file values\nos.environ['API_KEY'] = 'overridden_key_from_os'\n# No need to reload load_env, subsequent get_env calls will check os.environ first\nprint(f\"API Key (OS override): {get_env('API_KEY')}\")\n\n# Clean up the OS environment variable after the example\ndel os.environ['API_KEY']\n","lang":"python","description":"This quickstart demonstrates how to load environment variables from a `.env` file using `load_env()` and retrieve them with `get_env()`. It covers basic access, type casting (e.g., to bool or int), providing default values, and handling `EnvNotFoundError` for missing variables. It also highlights how OS environment variables take precedence over those in the `.env` file."},"warnings":[{"fix":"Use `get_env('VAR', cast_to_type=int)` or `int(get_env('VAR'))` for explicit type conversion.","message":"`get_env()` always returns a string by default. Remember to use the `cast_to_type` argument (e.g., `cast_to_type=int`, `cast_to_type=bool`) if you expect a non-string type.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To make `.env` file loading mandatory, use `load_env(critical=True)`. This will raise `EnvNotFoundError` if the file is not found.","message":"Since version 2.0.0, `load_env()` by default does *not* raise an `EnvNotFoundError` if the `.env` file is missing. It will simply proceed without loading variables from the file. If you require the `.env` file to be present, set `critical=True`.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"To ensure `.env` file variables are used, unset any conflicting OS environment variables, or ensure they are not set at all.","message":"Environment variables explicitly set in the operating system always take precedence over variables defined in the `.env` file. Be aware that `load_env()` will not override existing OS environment variables.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install env-tools` in your terminal.","cause":"The `env-tools` package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'env_tools'"},{"fix":"Either define 'MY_VARIABLE' in your `.env` file or OS environment, or provide a default value: `get_env('MY_VARIABLE', default='some_value')`.","cause":"You tried to access an environment variable using `get_env('MY_VARIABLE')` that is neither defined in your `.env` file, nor in your OS environment, and no `default` value was supplied to `get_env()`.","error":"env_tools.exceptions.EnvNotFoundError: Environment variable 'MY_VARIABLE' not found and no default provided."},{"fix":"Ensure the environment variable's value is compatible with the `cast_to_type` you are using (e.g., '123' for `int`, 'True'/'False' for `bool`). Implement validation or error handling if input might be malformed.","cause":"You used `cast_to_type=int` (or another type) with `get_env()`, but the value retrieved from the environment variable (e.g., 'not_an_int') could not be successfully converted to the specified type.","error":"ValueError: invalid literal for int() with base 10: 'not_an_int'"}]}