I need to set environment variables in a Python script so that other scripts called from Python can access them. When I try to set an environment variable with os.environ["DEBUSSY"] = 1, I get an error stating that the value must be a string. I also need to know how to read environment variables in Python after setting them.

NeuroAgent

Complete Guide to Python Environment Variables

Learn how to set and read environment variables in Python. Fix TypeError with string values, use os.environ.get() safely, and implement best practices for variable management.

#development-tips #environment-configuration #os-environ #python-best-practices #python-environment-variables #python-tutorial

11/07/2025, 05:04 PM

How to set and read environment variables in Python?

I need to set environment variables in a Python script so that other scripts called from Python can access them. When I try to set an environment variable with:

python

os.environ["DEBUSSY"] = 1

I get an error stating that the value must be a string. I also need to know how to read environment variables in Python after setting them.

NeuroAgent

Environment variables in Python must be set as strings, not integers or other data types. To fix your error, convert numeric values to strings using str() or directly assign string values. You can read environment variables using dictionary-style access with os.environ[key] or safer methods like os.environ.get(key, default).

Setting Environment Variables
Reading Environment Variables
Handling Missing Variables
Best Practices
Complete Example

Setting Environment Variables

When setting environment variables in Python, you must always use string values. The os.environ object treats environment variables as string mappings, and attempting to set non-string values will result in a TypeError.

Correct way to set environment variables:

python

import os

# Set string environment variable
os.environ["DEBUSSY"] = "1"
os.environ["API_KEY"] = "your-secret-key-here"
os.environ["DEBUG_MODE"] = "True"

# For numeric values, convert to string first
os.environ["PORT"] = str(8000)
os.environ["MAX_CONNECTIONS"] = str(100)

Common error and solution:

python

# This will raise TypeError: str expected, not int
os.environ["DEBUSSY"] = 1  # ❌ Incorrect

# Convert to string first
os.environ["DEBUSSY"] = str(1)  # ✅ Correct
# or directly use string
os.environ["DEBUSSY"] = "1"  # ✅ Correct

As noted in the research, “Environment variables are always strings” source. The os.environ object internally validates that all values are strings, throwing a TypeError with the message “str expected, not [type]” when non-string values are provided source.

Reading Environment Variables

There are several ways to read environment variables in Python, each with different error-handling behaviors:

1. Direct Dictionary Access

python

import os

# This will raise KeyError if variable doesn't exist
value = os.environ["DEBUSSY"]
print(value)  # Output: "1"

# To avoid KeyError, check first if variable exists
if "DEBUSSY" in os.environ:
    value = os.environ["DEBUSSY"]
    print(f"DEBUSSY is set to: {value}")

2. Using `os.environ.get()` Method

python

# Returns None if variable doesn't exist
value = os.environ.get("DEBUSSY")
print(value)  # Output: "1"

# Returns default value if variable doesn't exist
value = os.environ.get("NONEXISTENT_VAR", "default_value")
print(value)  # Output: "default_value"

3. Using `os.getenv()` Function

python

# Returns None if variable doesn't exist
value = os.getenv("DEBUSSY")
print(value)  # Output: "1"

# Returns default value if variable doesn't exist
value = os.getenv("NONEXISTENT_VAR", "default_value")
print(value)  # Output: "default_value"

As Mozilla Developer Network explains, the os.environ.get() method provides a safe way to access environment variables without raising exceptions for missing keys.

Handling Missing Variables

When working with environment variables, it’s crucial to handle cases where variables might not be set:

Safe Access Patterns

python

import os

# Method 1: Using get() with default value
database_url = os.environ.get("DATABASE_URL", "sqlite:///default.db")

# Method 2: Using get() and checking for None
api_key = os.environ.get("API_KEY")
if api_key is None:
    print("Warning: API_KEY not set")
    # Handle missing variable appropriately

# Method 3: Using try-except for required variables
try:
    required_var = os.environ["REQUIRED_VAR"]
except KeyError:
    print("Error: REQUIRED_VAR must be set")
    # Handle missing required variable

Checking for Variable Existence

python

# Check if variable exists
if "DEBUSSY" in os.environ:
    print("DEBUSSY is set")

# Get all environment variables
print("All environment variables:")
for key, value in os.environ.items():
    print(f"{key}={value}")

As mentioned in the research, “if you wish to assign a numeric value, ensure it is specified as a string” source. This applies equally to reading variables - always be prepared to handle missing or malformed values.

Best Practices

1. Always Use String Values

python

# ✅ Best practice
os.environ["CONFIG_VALUE"] = "true"

# ✅ Best practice for numeric values
os.environ["PORT"] = "8000"

# ❌ Avoid non-string values
os.environ["PORT"] = 8000  # TypeError!

2. Provide Sensible Defaults

python

# Use get() with meaningful defaults
debug_mode = os.environ.get("DEBUG_MODE", "false")
timeout = int(os.environ.get("TIMEOUT", "30"))

3. Required Variables Validation

python

def validate_environment():
    required_vars = ["DATABASE_URL", "API_KEY", "SECRET_KEY"]
    missing_vars = []
    
    for var in required_vars:
        if var not in os.environ:
            missing_vars.append(var)
    
    if missing_vars:
        raise EnvironmentError(f"Missing required variables: {', '.join(missing_vars)}")

# Call validation at startup
validate_environment()

4. Type Conversion After Reading

python

# Read as string, then convert to appropriate type
port_str = os.environ.get("PORT", "8000")
port = int(port_str)

debug_str = os.environ.get("DEBUG", "false")
debug = debug_str.lower() in ("true", "1", "yes")

5. Security Considerations

python

# Never log sensitive environment variables
api_key = os.environ.get("API_KEY")
if api_key:
    print(f"API key length: {len(api_key)}")  # Safe
    # print(f"API key: {api_key}")  # Unsafe!

Complete Example

Here’s a comprehensive example demonstrating proper environment variable handling:

python

import os
import json
from typing import Optional, Dict, Any

class EnvironmentManager:
    """A class to manage environment variables with type conversion and validation."""
    
    @staticmethod
    def set_env_var(key: str, value: Any) -> None:
        """Set an environment variable, converting non-string values to strings."""
        if not isinstance(value, str):
            value = str(value)
        os.environ[key] = value
    
    @staticmethod
    def get_env_var(key: str, default: Optional[str] = None) -> Optional[str]:
        """Get an environment variable with optional default value."""
        return os.environ.get(key, default)
    
    @staticmethod
    def get_env_var_int(key: str, default: int = 0) -> int:
        """Get an environment variable as integer."""
        value = os.environ.get(key, str(default))
        try:
            return int(value)
        except ValueError:
            raise ValueError(f"Cannot convert '{key}' value '{value}' to integer")
    
    @staticmethod
    def get_env_var_bool(key: str, default: bool = False) -> bool:
        """Get an environment variable as boolean."""
        value = os.environ.get(key, str(default)).lower()
        return value in ("true", "1", "yes", "on")
    
    @staticmethod
    def validate_required_vars(*required_vars: str) -> None:
        """Validate that all required environment variables are set."""
        missing_vars = [var for var in required_vars if var not in os.environ]
        if missing_vars:
            raise EnvironmentError(f"Missing required environment variables: {missing_vars}")

# Example usage
if __name__ == "__main__":
    # Set some environment variables
    EnvironmentManager.set_env_var("APP_NAME", "MyApplication")
    EnvironmentManager.set_env_var("DEBUG_MODE", True)  # Will be converted to "True"
    EnvironmentManager.set_env_var("PORT", 8080)  # Will be converted to "8080"
    EnvironmentManager.set_env_var("API_KEY", "secret-12345")
    
    # Read environment variables with type conversion
    app_name = EnvironmentManager.get_env_var("APP_NAME")
    debug_mode = EnvironmentManager.get_env_var_bool("DEBUG_MODE")
    port = EnvironmentManager.get_env_var_int("PORT")
    api_key = EnvironmentManager.get_env_var("API_KEY")
    
    print(f"App Name: {app_name}")
    print(f"Debug Mode: {debug_mode}")
    print(f"Port: {port}")
    print(f"API Key: {'*' * len(api_key)}")  # Hide sensitive info
    
    # Validate required variables
    try:
        EnvironmentManager.validate_required_vars("DATABASE_URL", "SECRET_KEY")
    except EnvironmentError as e:
        print(f"Configuration Error: {e}")
    
    # Demonstrate error handling
    try:
        invalid_port = EnvironmentManager.get_env_var_int("INVALID_PORT", "not_a_number")
    except ValueError as e:
        print(f"Error: {e}")

This example provides a robust framework for handling environment variables in Python applications, including type conversion, validation, and error handling.

Sources

Conclusion

Environment variables in Python must always be set as string values, not integers or other data types
Use os.environ[key] = str(value) to properly set environment variables
Read environment variables using os.environ.get(key, default) for safe access without KeyError exceptions
Convert string values to appropriate types after reading them from environment variables
Implement proper validation for required environment variables in your applications
Use type conversion methods to safely handle numeric and boolean values stored as strings in environment variables

By following these practices, you can effectively manage environment variables in Python applications while avoiding common errors like the TypeError you encountered.

How to handle environment variables in Python applications with different environments (development, staging, production)?What are the security best practices for storing sensitive data in environment variables?How to load environment variables from .env files in Python?How to validate environment variables in Python applications?What's the difference between os.environ and os.getenv() in Python?How to set environment variables permanently in Python for different operating systems?

Ask NeuroAgent

Complete Guide to Python Environment Variables

Contents

Setting Environment Variables

Reading Environment Variables

1. Direct Dictionary Access

2. Using os.environ.get() Method

3. Using os.getenv() Function

Handling Missing Variables

Safe Access Patterns

Checking for Variable Existence

Best Practices

1. Always Use String Values

2. Provide Sensible Defaults

3. Required Variables Validation

4. Type Conversion After Reading

5. Security Considerations

Complete Example

Sources

Conclusion

2. Using `os.environ.get()` Method

3. Using `os.getenv()` Function