Skip to content

Get Started here

Venvalid logo

Minimalist environment variable validation for Python, inspired by envalid

About

Venvalid is a minimalist and developer-friendly environment variable validator for Python — inspired by the simplicity and clarity of envalid from the Node.js world.

It lets you define a schema for your environment variables and ensures they are present, well-formed, and ready to use — before your app even starts.

Why Venvalid?

Venvalid was designed with Python developers in mind, offering a modern, clean, and extensible API to handle .env configurations. It stands out from other libraries by:

  • ✅ Using Python native types (str, bool, int, list, Path, Decimal, datetime, etc.)
  • ✅ Supporting default values, enum constraints, and custom validation
  • ✅ Allowing custom dotenv loading with override support
  • ✅ Raising clear and styled error messages that prevent app boot on misconfig
  • ✅ Having zero external dependencies — just Python

Installation

pip install venvalid

or

uv add venvalid

Quick Example

from venvalid import str_, int_, bool_, venvalid
from venvalid.dotenv import load_env_file

# Define schema
config = venvalid({
    "DEBUG": bool_(default=False),
    "PORT": int_(default=8000),
    "SECRET_KEY": str_(),
    "ENVIRONMENT": str_(allowed=["dev", "prod", "test"], default="dev"),
})

print(config["DEBUG"])        # -> False
print(config["PORT"])         # -> 8000
print(config["ENVIRONMENT"])  # -> "dev"

Usage

You can use venvalid to validate configuration before mounting the app:

from fastapi import FastAPI
from venvalid import str_, int_, bool_, venvalid
from venvalid.dotenv import load_env_file

config = venvalid({
    "DEBUG": bool_(default=False),
    "PORT": int_(default=8000),
    "ENVIRONMENT": str_(allowed=["dev", "prod", "test"], default="dev"),
})

app = FastAPI()

@app.get("/")
def read_root():
    return {
        "env": config["ENVIRONMENT"],
        "debug": config["DEBUG"],
        "port": config["PORT"],
    }

Supported Types

You can use both built-in types and helper functions:

  • str, int, bool, list
  • path_() → for pathlib.Path
  • decimal_() → for Decimal
  • datetime_() → for datetime
  • json_() → for JSON/dict strings

All helpers accept:

  • default=...
  • allowed=[...]
  • validate=callable

Advanced Options

"ENVIRONMENT": str_(allowed=["dev", "prod"], default="dev"),
"FEATURE_FLAG": bool_(default=False),
"API_KEY": str_(validate=lambda v: v.startswith("sk-")),

If any variable is missing or invalid, venvalid will stop execution and print a meaningful error message.

.env Loading

If you want to load variables from a .env file (without relying on python-dotenv), use:

from venvalid.dotenv import load_env_file

load_env_file(".env")             # default
load_env_file(".env.prod", override=True)  # optional override