Install & Compatibility
Where this runs
tested against v1.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
72MB installed
● package 72MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
settings
✓ from simple_settings import settings
✗ import simple_settings.settings
The `settings` object is a singleton that gets populated when the settings module is identified.
LazySettings
✓ from simple_settings import LazySettings
Use `LazySettings` for explicit control over settings file loading, or when avoiding the global singleton.
This quickstart demonstrates how to define a Python settings file and load it using `LazySettings`. In a typical application, the settings module would be specified via a `--settings` command-line argument (e.g., `python your_app.py --settings=my_project_settings.development`) or the `SIMPLE_SETTINGS` environment variable, after which the global `simple_settings.settings` object becomes populated. Using `LazySettings` allows for explicit, programmatic control over which settings module to load.
import os
import sys
from simple_settings import settings
# --- Create a dummy settings file for demonstration ---
settings_content = """
FOO = 'bar'
BAZ = 123
SIMPLE_SETTINGS = {'required_settings': ['FOO']}
"""
settings_dir = 'my_project_settings'
os.makedirs(settings_dir, exist_ok=True)
with open(os.path.join(settings_dir, 'development.py'), 'w') as f:
f.write(settings_content)
# Add the settings directory to Python's path so it can be imported
sys.path.insert(0, os.getcwd())
# Method 1: Set environment variable (deprecated but common in older setups)
# os.environ['SIMPLE_SETTINGS'] = 'my_project_settings.development'
# Method 2: Command line argument (preferred for non-programmatic loading)
# For programmatic loading, you'd typically use LazySettings or a custom loader
# For this quickstart, we'll demonstrate direct access after 'setting' the module path implicitly.
# In a real app, you would run like: python your_script.py --settings=my_project_settings.development
# As a workaround for a runnable quickstart, we'll manually set the internal _SETTINGS_MODULE
# This is NOT how you'd normally configure it in production for the 'settings' singleton
# Normally, the --settings CLI arg or SIMPLE_SETTINGS env var would handle this.
# Using LazySettings is the programmatic alternative.
# For this demonstration, we'll mimic the effect of `settings.configure()`
# if the env var or CLI was set.
# In a real application, you'd run `python your_app.py --settings=my_project_settings.development`
# and then `from simple_settings import settings` would automatically pick it up.
# To make this runnable without CLI args or env vars, we use LazySettings.
try:
# Using LazySettings for a self-contained programmatic example
app_settings = LazySettings('my_project_settings.development')
print(f"FOO setting: {app_settings.FOO}")
print(f"BAZ setting: {app_settings.BAZ}")
# Demonstrate a missing required setting (this would raise an error)
# with open(os.path.join(settings_dir, 'broken_settings.py'), 'w') as f:
# f.write("BAZ = 456")
# broken_app_settings = LazySettings('my_project_settings.broken_settings')
# print(f"Broken FOO: {broken_app_settings.FOO}")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up dummy settings file and directory
os.remove(os.path.join(settings_dir, 'development.py'))
# if os.path.exists(os.path.join(settings_dir, 'broken_settings.py')):
# os.remove(os.path.join(settings_dir, 'broken_settings.py'))
os.rmdir(settings_dir)
sys.path.pop(0)
simple_settings --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'your_settings_module'
The Python interpreter cannot find the specified settings module. This usually means the module path provided via `--settings` or `SIMPLE_SETTINGS` is incorrect, or the directory containing the settings file is not in Python's `sys.path`.
fixVerify the settings module path (e.g., `my_project.settings.development`). Ensure the directory containing `my_project` (or the top-level package) is in `PYTHONPATH` or added to `sys.path`.
TypeError: 'NoneType' object is not iterable (or similar error related to empty config files)
In versions prior to 1.1.0, loading an entirely empty settings file (e.g., an empty YAML or JSON file) could lead to a TypeError. This was fixed in 1.1.0 but could appear in older installations or specific edge cases.
fixUpgrade to `simple-settings` version 1.1.0 or newer. Ensure configuration files are not entirely empty, or at least contain valid, minimal content if intended to be empty (e.g., `{}` for JSON/YAML). Upgrade
Version history
1.2.0latest on PyPI · released Dec 30, 2021
Audit
Dependencies
PyYAMLoptionalRequired for loading settings from YAML files.
tomloptionalRequired for loading settings from TOML files.
boto3optionalRequired for using AWS S3 as a dynamic settings backend.
python-memcachedoptionalRequired for using Memcached as a dynamic settings backend.
SQLAlchemyoptionalRequired for using a database (via SQLAlchemy) as a dynamic settings backend.