envsubst Command
Beginner Text Processing man(1)Substitute environment variables in text
👁 118 views
📅 Updated: May 1, 2026
SYNTAX
envsubst [VARIABLES] < TEMPLATE > OUTPUT
What Does envsubst Do?
The envsubst command substitutes environment variable references in text with their values. It reads from stdin (or files) and replaces $VARIABLE and ${VARIABLE} patterns with the corresponding environment variable values.
envsubst is essential for configuration management and container deployments where configuration files need to be templated with environment-specific values. Instead of maintaining separate config files for development, staging, and production, you maintain one template and use envsubst to fill in the values at deployment time.
This is a core pattern in Docker/Kubernetes deployments, CI/CD pipelines, and infrastructure-as-code. Nginx, Apache, application configs, and any text-based configuration file can be templated with envsubst. It is simpler and more secure than using sed for variable substitution, as it does not require escaping special regex characters.
envsubst is essential for configuration management and container deployments where configuration files need to be templated with environment-specific values. Instead of maintaining separate config files for development, staging, and production, you maintain one template and use envsubst to fill in the values at deployment time.
This is a core pattern in Docker/Kubernetes deployments, CI/CD pipelines, and infrastructure-as-code. Nginx, Apache, application configs, and any text-based configuration file can be templated with envsubst. It is simpler and more secure than using sed for variable substitution, as it does not require escaping special regex characters.
Options & Flags
| Option | Description | Example |
|---|---|---|
| (basic usage) | Substitute all environment variables | envsubst < template.conf > output.conf |
| ' ' | Substitute only specified variables | envsubst '$DB_HOST $DB_PORT' < template.conf > output.conf |
| -v | Print version and exit | envsubst -v |
| -V | List all recognized variable references | envsubst -V < template.conf |
Practical Examples
#1 Template a config file
Replace $DB_HOST, $DB_PORT, $DB_NAME in template with actual values.
$ export DB_HOST=10.0.0.5 DB_PORT=5432 DB_NAME=myapp && envsubst < db.conf.template > db.conf#2 Nginx config template
Generate Nginx config from template. Only substitute specified variables (leave other $ signs untouched).
$ export SERVER_NAME=example.com BACKEND_PORT=3000 && envsubst '$SERVER_NAME $BACKEND_PORT' < /etc/nginx/templates/default.conf.template > /etc/nginx/conf.d/default.conf#3 Docker entrypoint pattern
Common Docker entrypoint pattern: generate config from template using runtime env vars, then start the app.
$ #!/bin/sh\nenvsubst < /app/config.template.js > /app/config.js\nexec "$@"#4 Inline template
Use with echo for simple templating. Note: single quotes prevent shell expansion, envsubst does the substitution.
$ export NAME=World && echo 'Hello $NAME, today is $TODAY' | envsubst
Output:
Hello World, today is
#5 Selective substitution
Only replace $APP_PORT, leaving other $variables unchanged. Essential when template contains literal $ signs.
$ export APP_PORT=8080 && envsubst '$APP_PORT' < template.yml > output.yml#6 Kubernetes ConfigMap template
Template a Kubernetes manifest and apply it directly. Common in CI/CD pipelines for per-environment deployments.
$ export ENVIRONMENT=production DB_URL=postgres://... && envsubst < k8s/configmap.template.yaml | kubectl apply -f -#7 Generate .env file
Create environment-specific .env files from a template. Keep .env.template in git, generate .env at deploy time.
$ export API_KEY="sk-123" DB_URL="postgres://..." && envsubst < .env.template > .envTips & Best Practices
Specify variables to substitute: Always specify which variables to substitute when your template contains literal $ signs: envsubst '$VAR1 $VAR2' < template. Otherwise ALL $ references are replaced.
Missing variables become empty: Undefined environment variables are replaced with empty strings. Use set -u in scripts to catch missing variables, or validate required vars before envsubst.
Part of gettext: envsubst is part of the gettext package. Install: apt install gettext (Debian/Ubuntu), dnf install gettext (Fedora/RHEL).
Docker best practice: In Dockerfiles, copy templates and use envsubst in the entrypoint script. This keeps images environment-agnostic — the same image works in dev, staging, and production.
Frequently Asked Questions
How do I substitute environment variables in a config file?
Use: envsubst < template.conf > output.conf. The template uses $VARIABLE or ${VARIABLE} syntax. Set variables with export VAR=value before running.
How do I substitute only specific variables?
List them: envsubst '$VAR1 $VAR2' < template > output. Only $VAR1 and $VAR2 are replaced; other $ references remain untouched.
What happens if a variable is not defined?
envsubst replaces it with an empty string. To catch this, check required variables before running: [ -z \"$VAR\" ] && echo \"VAR required\" && exit 1.
How is envsubst used in Docker?
In an entrypoint script: envsubst < config.template > config.conf && exec "$@". This generates runtime config from environment variables passed to the container.
Related Commands
More Text Processing Commands
Download Text Processing Cheat Sheet
View all 31 Linux command cheat sheets →Master Linux with Professional eBooks
Curated IT eBooks covering Linux, DevOps, Cloud, and more
Browse Books →