---
id: envsubst
version: "0.1.5"
license: MIT
license_treatment: permissive
maintenance: abandoned
---

# envsubst — Substitute environment variables in a string

License: permissive · Maintenance: abandoned · Downloads: 144.9K/mo

## What it is and what it does

envsubst is a lightweight utility for performing shell-style environment variable substitution within Python strings. It parses strings containing variable references like `$VAR` or `${VAR}` and replaces them with their corresponding environment variable values. The package supports default value syntax—`${VAR:-default}` uses a default if the variable is unset, and `${VAR-default}` uses a default only if the variable is unset or empty—mirroring common shell behavior.

The package has no runtime dependencies and installs as a pure Python wheel, making it simple to add to any project. However, it has been abandoned since its last release in October 2019, with no commits to the repository since July 2023. This means any bugs or compatibility issues with newer Python versions will not be fixed by the maintainer.

Use it for:

- Substitute environment variables into configuration strings or templates at runtime without external templating libraries.
- Parse and expand shell-like variable references in user-provided strings or configuration files.
- Build dynamic command strings or paths that depend on environment variables with fallback defaults.
- Migrate shell scripts to Python while preserving variable substitution syntax familiar to shell users.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Substitutes environment variables in strings using shell-like syntax, supporting both simple variable references and default value expressions.

Yes, if you need simple shell-style variable substitution and can accept that the package is unmaintained. The low install friction and permissive MIT license make it a lightweight choice for straightforward use cases. No, if you require active maintenance, Python version compatibility guarantees, or support for complex templating—consider a maintained alternative or implement substitution inline.

## Install

pip install envsubst
uv add envsubst
poetry add envsubst

## Installing envsubst

Before you install: Install friction is low with no runtime dependencies. However, the package is abandoned—last release was 2019-10-05 and the repository shows no commits since 2023-07-07. No active maintenance means security or compatibility issues will not be addressed.

License in practice: Licensed under MIT (permissive), so you can use, modify, and distribute the package freely with minimal restrictions.

Quickstart:

import os
from envsubst import envsubst

os.environ['USER'] = 'alice'
os.environ['HOST'] = 'example.com'
result = envsubst('$USER@$HOST')
print(result)  # alice@example.com

Verify before relying:

- Whether the package works correctly with modern Python versions (requires_python is unspecified)
- Whether argv-based substitution ($0, $1, etc.) is fully documented or tested
- Whether nested or complex variable references beyond the documented examples are supported

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: abandoned
- Downloads: 144.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

environment variable substitution, shell variable expansion, envsubst python, substitute env vars in string, variable interpolation, default value fallback, shell-like variable syntax, shell-compatibility, abandoned

[View on SkillFed](https://skillfed.io/packages/envsubst) · [View on PyPI](https://pypi.org/project/envsubst/)