---
id: expandvars
version: "1.1.2"
license: MIT License Copyright (c) 2019 Arijit Basu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal… (full text in the JSON record)
license_treatment: permissive
maintenance: aging
---

# expandvars — Expand system variables Unix style

License: permissive · Maintenance: aging · Downloads: 3.5M/mo

## What it is and what it does

expandvars is a Python module that parses and expands environment variable references in strings using bash-like syntax. It goes beyond Python's built-in os.path.expandvars by supporting advanced features: default values (${VAR:-default}), error-on-undefined (${VAR:?}), variable indirection (${!VAR}), and strict mode (nounset=True). It has no runtime dependencies and is designed primarily for reading configuration files that need flexible environment variable interpolation.

The module copies most common bash behaviors but does not attempt full bash compliance—for example, it does not support arrays. You can customize the variable symbol, escape character, and expansion data via the lower-level expand() function. It also respects an EXPANDVARS_RECOVER_NULL environment variable to temporarily disable strict parsing in testing scenarios.

Use it for:

- Parse TOML or INI config files that reference environment variables with fallback defaults.
- Build file paths dynamically by expanding $HOME, $PATH, and custom environment variables in application startup.
- Validate that required environment variables are set before running a service, using ${VAR:?} syntax.
- Substitute secrets and credentials from environment into configuration templates without hardcoding.
- Support nested variable references where one env var points to the name of another to resolve.

## Worth the install?

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

Expands Unix-style variable references in strings with bash-like syntax, supporting default values, error handling, and nested variable lookups as an alternative to Python's os.path.expandvars.

Yes. expandvars is a lightweight, dependency-free utility with permissive licensing and no known vulnerabilities. It solves a real problem—flexible environment variable expansion in config files—more elegantly than os.path.expandvars. Aging maintenance is not a concern for a stable, narrow-scope tool. Install if you need bash-style variable syntax in configuration or string interpolation.

## Install

pip install expandvars
uv add expandvars
poetry add expandvars

## Installing expandvars

Before you install: Low install friction with no runtime dependencies. Aging maintenance status (336 days since last release) but repository remains active with recent commits; stable for a utility of this scope.

License in practice: MIT License permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

from expandvars import expandvars

result = expandvars("$PATH:${HOME:?}/bin:${UNDEFINED:-/default}")
print(result)

Requires Python 3.6.2 or later.

Verify before relying:

- Whether the package handles all edge cases in production config-file parsing workflows.
- Performance characteristics when expanding very large strings or deeply nested variables.

## Package facts

- License: MIT License Copyright (c) 2019 Arijit Basu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 3.5M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

bash variable expansion, environment variable substitution, unix style variable expansion, config file variable interpolation, shell parameter expansion python, config-parsing, environment-variables

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