Environment file generator with template + override support.
Born from MochatAI team's production experience building cross-border e-commerce and Amazonn Ads Agent.
Most dotenv libraries load .env files at runtime. But generating .env files can be frustrating:
- Building Docker images that need baked-in environment configs, but your project only has
.env.example, not.env? - Already have
.env.exampleand.env.{env}, but that's not enough? Those files are committed to git, but you need to temporarily change configs for debugging without committing - Parallel development with worktrees? Each worktree needs its own independent configuration
env-patch generates a single .env file at build time by merging .env.example (template), .env.development (environment config), and .env.development.local (local overrides).
Global CLI (recommended for most users):
# Using pipx
pipx install env-patch
# Using uv tool (if you use uv)
uv tool install env-patchAs a project dependency:
# Using pip
pip install env-patch
# Using uv
uv add env-patch# 1. Create your template
cat > .env.example << 'EOF'
DATABASE_URL=postgres://localhost/myapp
REDIS_URL=redis://localhost:6379
DEBUG=false
EOF
# 2. Create environment-specific config
cat > .env.development << 'EOF'
DEBUG=true
EOF
# 3. Generate .env
env-patch -e development
# Result: .env contains DATABASE_URL, REDIS_URL from template + DEBUG=true from override.env.example # Template (git tracked)
.env.development # Development config (git tracked)
.env.development.local # Local overrides (git ignored)
.env # Output (git ignored)
Priority (highest to lowest):
.env.{env}.local- Personal machine-specific overrides.env.{env}- Environment-specific config.env.example- Default template values
# Auto-detect env file (when only one exists)
env-patch
# Specify environment
env-patch -e development
env-patch -e production
env-patch -e stagingBuilt-in aliases for common environments:
env-patch -e dev # Same as: env-patch -e development
env-patch -e prod # Same as: env-patch -e production
env-patch -e stage # Same as: env-patch -e staging# Use any environment name
env-patch -e uai-prod # Uses .env.uai-prod
env-patch -e feature-auth # Uses .env.feature-authenv-patch -e <env> # Environment name
env-patch -t <file> # Template file (default: .env.example)
env-patch -o <file> # Output file (default: .env)
env-patch -s # Strict mode: error on unknown keys
env-patch -h # Show help
env-patch -v # Show versionCreate .env.{env}.local for machine-specific settings that shouldn't be committed:
# .env.development.local (git ignored)
DATABASE_URL=postgres://localhost:5433/myapp_local
API_KEY=my-personal-api-keyThese values override both the template and the environment config.
# Output file
.env
# Local overrides
.env.local
.env.*.local
# Keep these tracked
!.env.example# GitHub Actions example
steps:
- name: Generate .env for production
run: |
pip install env-patch
env-patch -e production# Dockerfile example
FROM python:3.12
RUN pip install env-patch
COPY .env.example .env.production ./
RUN env-patch -e production| Feature | env-patch | dotenv-flow |
|---|---|---|
| When it runs | Build time | Runtime |
| Output | Single .env file |
In-memory only |
| Docker builds | Easy | Requires workaround |
| Debug visibility | Check .env directly |
Add logging |
| Language | Python CLI | Node.js library |
Use env-patch when you need a generated file. Use dotenv-flow when you want runtime loading.
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License - see LICENSE for details.
env-patch： .env 文件生成器，支持模板 + 覆盖机制。
源自 MochatAI 团队在跨境电商AI(特别是亚马逊AI广告经理)开发中的实战经验。
大多数编程语言的 dotenv 库在 运行时 会加载 .env 文件。但 .env 文件的生成就搞得人很烦，比如：
- 在构建 Docker 镜像 时需要内置环境配置，但项目里只有
.env.example，没有.env文件？ - 有了
.env.example和.env.{env}(比如.env.development)，结果还不够，因为团那些文件也都是提交到 git 仓库的，所以一旦频繁修改就以为需要提交git或反复注意有没有不小心提交到git，但我们在调试时希望临时改变一下配置，但不希望提交到 git仓库 - 在 worktree 并行开发时，希望每个 worktree 都有自己独立的配置
env-patch 在 构建时 就可以将 .env.example、.env.development（环境配置）、.env.development.local（环境配置的本地覆盖）合并生成单一 .env 文件。
全局 CLI（推荐大多数用户使用）：
# 使用 pipx
pipx install env-patch
# 使用 uv tool（如果你使用 uv）
uv tool install env-patch作为项目依赖：
# 使用 pip
pip install env-patch
# 使用 uv
uv add env-patch# 1. 创建模板
cat > .env.example << 'EOF'
DATABASE_URL=postgres://localhost/myapp
REDIS_URL=redis://localhost:6379
DEBUG=false
EOF
# 2. 创建环境配置
cat > .env.development << 'EOF'
DEBUG=true
EOF
# 3. 生成 .env
env-patch -e development
# 结果：.env 包含模板的 DATABASE_URL、REDIS_URL + 覆盖的 DEBUG=true.env.example # 模板（git 追踪）
.env.development # 开发环境配置（git 追踪）
.env.development.local # 本地覆盖（git 忽略）
.env # 输出文件（git 忽略）
优先级（从高到低）：
.env.{env}.local- 个人机器特定的覆盖.env.{env}- 环境配置.env.example- 模板默认值
# 自动检测环境文件（当只有一个时）
env-patch
# 指定环境
env-patch -e development
env-patch -e production
env-patch -e staging内置常用环境别名：
env-patch -e dev # 等同于: env-patch -e development
env-patch -e prod # 等同于: env-patch -e production
env-patch -e stage # 等同于: env-patch -e staging# 使用任意环境名
env-patch -e uai-prod # 使用 .env.uai-prod
env-patch -e feature-auth # 使用 .env.feature-authenv-patch -e <env> # 环境名称
env-patch -t <file> # 模板文件（默认: .env.example）
env-patch -o <file> # 输出文件（默认: .env）
env-patch -s # 严格模式：未知键报错
env-patch -h # 显示帮助
env-patch -v # 显示版本创建 .env.{env}.local 存放不应提交的机器特定配置：
# .env.development.local（git 忽略）
DATABASE_URL=postgres://localhost:5433/myapp_local
API_KEY=my-personal-api-key这些值会覆盖模板和环境配置。
# 输出文件
.env
# 本地覆盖
.env.local
.env.*.local
# 保留这些追踪
!.env.example# GitHub Actions 示例
steps:
- name: 生成生产环境 .env
run: |
pip install env-patch
env-patch -e production# Dockerfile 示例
FROM python:3.12
RUN pip install env-patch
COPY .env.example .env.production ./
RUN env-patch -e production欢迎贡献！提交 Pull Request 为开源做贡献。
MIT License - 详见 LICENSE
Made with love by MochatAI Team