envsubst Python Library

Common errors

• KeyError: 'ENV_VAR_NAME'

  cause Attempting to access an environment variable using `os.environ['ENV_VAR_NAME']` directly, but the variable is not set in the current environment.
  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}`).

• Command 'envsubst' not found

  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.
  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).

Warnings

• gotcha 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.
  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}')`.
• deprecated 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`.
  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).
• gotcha 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.
  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.

Install

• pip install envsubst Install latest version

Imports

• envsubst

  from envsubst import envsubst

Quickstart

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.

import os
from envsubst import envsubst

# Example 1: Basic substitution
os.environ['MY_APP_NAME'] = 'MyAwesomeApp'
template_string = "The application name is: ${MY_APP_NAME}."
result = envsubst(template_string)
print(f"Basic substitution: {result}")
# Expected: "The application name is: MyAwesomeApp."

# Example 2: Substitution with default value (if variable is unset or empty)
# Clear the variable to demonstrate default
if 'FEATURE_FLAG' in os.environ:
    del os.environ['FEATURE_FLAG']
template_with_default = "Feature status: ${FEATURE_FLAG:-disabled}."
result_default = envsubst(template_with_default)
print(f"With default (unset): {result_default}")
# Expected: "Feature status: disabled."

os.environ['FEATURE_FLAG'] = 'enabled'
result_default_set = envsubst(template_with_default)
print(f"With default (set): {result_default_set}")
# Expected: "Feature status: enabled."

# Clean up environment variables used (good practice for scripts)
del os.environ['MY_APP_NAME']
if 'FEATURE_FLAG' in os.environ:
    del os.environ['FEATURE_FLAG']