{"id":8976,"library":"envsubst","title":"envsubst Python Library","description":"The `envsubst` library for Python provides functionality to substitute environment variables in a string, mimicking the behavior of the GNU `envsubst` command-line utility. It supports `$VAR` and `${VAR}` style variable expansions, including the use of default values like `${VAR:-default}`. The current version is 0.1.5, with its last release in October 2019, indicating a maintenance-only or inactive development cadence.","status":"active","version":"0.1.5","language":"en","source_language":"en","source_url":"https://github.com/ashafer01/python-envsubst","tags":["environment variables","templating","configuration","string substitution"],"install":[{"cmd":"pip install envsubst","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"envsubst","correct":"from envsubst import envsubst"}],"quickstart":{"code":"import os\nfrom envsubst import envsubst\n\n# Example 1: Basic substitution\nos.environ['MY_APP_NAME'] = 'MyAwesomeApp'\ntemplate_string = \"The application name is: ${MY_APP_NAME}.\"\nresult = envsubst(template_string)\nprint(f\"Basic substitution: {result}\")\n# Expected: \"The application name is: MyAwesomeApp.\"\n\n# Example 2: Substitution with default value (if variable is unset or empty)\n# Clear the variable to demonstrate default\nif 'FEATURE_FLAG' in os.environ:\n    del os.environ['FEATURE_FLAG']\ntemplate_with_default = \"Feature status: ${FEATURE_FLAG:-disabled}.\"\nresult_default = envsubst(template_with_default)\nprint(f\"With default (unset): {result_default}\")\n# Expected: \"Feature status: disabled.\"\n\nos.environ['FEATURE_FLAG'] = 'enabled'\nresult_default_set = envsubst(template_with_default)\nprint(f\"With default (set): {result_default_set}\")\n# Expected: \"Feature status: enabled.\"\n\n# Clean up environment variables used (good practice for scripts)\ndel os.environ['MY_APP_NAME']\nif 'FEATURE_FLAG' in os.environ:\n    del os.environ['FEATURE_FLAG']","lang":"python","description":"This quickstart demonstrates how to import and use the `envsubst` function to replace environment variables in a string. It covers both basic substitution and using default values when a variable is unset or empty. The example explicitly sets and cleans up environment variables for reproducible results."},"warnings":[{"fix":"Always use default value syntax (`${VAR:-default}`) if the variable might be unset or empty and a fallback is desired. E.g., `envsubst('${DATABASE_URL:-sqlite:///data.db}')`.","message":"When a referenced environment variable (e.g., `$VAR` or `${VAR}`) is not set or is an empty string, `envsubst` will replace it with an empty string by default, potentially leading to unintended blank values in your output if a default is not specified.","severity":"gotcha","affected_versions":"0.1.0-0.1.5"},{"fix":"For new projects or if advanced features (e.g., custom resolvers, Rust performance) are required, consider alternatives such as `varsubst` (pip install varsubst) or `envsub` (pip install envsub).","message":"The `envsubst` library has not seen updates since October 2019. While functional for its stated purpose, it might lack modern features or bug fixes present in more actively maintained alternatives like `varsubst` or `envsub`.","severity":"deprecated","affected_versions":"0.1.0-0.1.5"},{"fix":"To modify a file, read its content, process with `envsubst`, and then write the result back to the file (or a new file). For shell scripting, use a temporary file or `sponge` for in-place edits.","message":"The Python `envsubst` library processes strings in memory. It does not provide direct 'in-place' file modification like the shell command can sometimes appear to (with caveats). Attempting `envsubst < file.txt > file.txt` in shell will truncate the file.","severity":"gotcha","affected_versions":"0.1.0-0.1.5"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"When fetching environment variables that might not be set, use `os.environ.get('ENV_VAR_NAME', 'default_value')` to provide a fallback, or ensure the variable is always set before runtime. The `envsubst` function itself will substitute unset variables with empty strings if no default is provided in the template (e.g., `${ENV_VAR_NAME:-default}`).","cause":"Attempting to access an environment variable using `os.environ['ENV_VAR_NAME']` directly, but the variable is not set in the current environment.","error":"KeyError: 'ENV_VAR_NAME'"},{"fix":"If you intend to use the Python library, ensure you are importing and calling `envsubst` within your Python code (`from envsubst import envsubst`). If you need the shell command, install `gettext` (e.g., `brew install gettext` on macOS, `sudo apt-get install gettext-base` on Debian/Ubuntu).","cause":"This error typically indicates that the GNU `envsubst` command-line utility is not installed or not in the system's PATH, rather than an issue with the Python `envsubst` library. It's common on macOS without `gettext` installed.","error":"Command 'envsubst' not found"}]}