Venvalid: A Python repository from PinnLabs

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

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

PinnLabs/Venvalid