Registry / web-framework / django-appconf

django-appconf

JSON →
library1.2.0pypypi✓ verified 26d ago

django-appconf is a helper class designed to manage configuration defaults gracefully within packaged Django applications. It simplifies defining, documenting, and overriding application-specific settings, preventing direct manipulation of `django.conf.settings`. As of version 1.2.0, it remains actively maintained, with a focus on modern Python and Django versions.

pip install django-appconf
INSTALL
IMPORT
SIG · DJANGO-APPCONF
D
django-appconf
web-frameworkpythonv1.2.0
Install
3.4s avg
Import
28ms
Disk
66MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.026s · 66.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.4s · import 0.030s · 67MB
66MB installed
● package 66MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AppConf
from appconf import AppConf

Define your application's default settings by subclassing `AppConf` within your app (e.g., in `your_app/conf.py`). It is critical to ensure your `AppConf` subclass is imported during Django's startup. The recommended approach is to import it within your app's `AppConfig.ready()` method (defined in `your_app/apps.py`), which is guaranteed to run once Django's app registry is fully populated. Settings can then be accessed via `django.conf.settings` using the defined prefix (e.g., `MYAPP_SETTING_1`). Project-level settings in `settings.py` can override these defaults.

import os from django.apps import AppConfig from appconf import AppConf # app_name/conf.py class MyAppConf(AppConf): MYAPP_SETTING_1 = "default_value_1" MYAPP_SETTING_2 = { "key": "default_value_2" } class Meta: prefix = 'MYAPP' # Explicitly set prefix, often defaults to capitalized app label def configure_myapp_setting_1(self, value): # Example of custom configuration logic, must return a value if os.environ.get('OVERRIDE_SETTING_1'): return os.environ.get('OVERRIDE_SETTING_1') return value # app_name/apps.py class MyAppConfig(AppConfig): name = 'app_name' verbose_name = 'My Application' def ready(self): super().ready() # Import AppConf subclass here to ensure it's loaded during startup try: # This import triggers the MyAppConf to load its settings from . import conf except ImportError: pass # Handle gracefully if conf.py doesn't exist or has issues # Example of how settings are accessed elsewhere (e.g., views.py, models.py) # Ensure Django settings are configured (e.g., through a Django project's settings.py) # In a Django project's settings.py, you would add: # INSTALLED_APPS = [ # 'app_name.apps.MyAppConfig', # # ... other apps # ] # MYAPP_SETTING_1 = "project_override_value" # To demonstrate accessing the settings after Django is ready from django.conf import settings def get_my_settings(): # Accessing settings via django.conf.settings is recommended setting1 = settings.MYAPP_SETTING_1 setting2 = settings.MYAPP_SETTING_2 return f"Setting 1: {setting1}, Setting 2: {setting2}" # This part would typically be run within a Django context # For demonstration, simulate Django setup minimaly if not in a full project if not hasattr(settings, 'configure'): from django.conf import settings settings.configure( INSTALLED_APPS=['app_name.apps.MyAppConfig'], MYAPP_SETTING_1="configured_default_via_settings", SECRET_KEY='a-very-secret-key', DEBUG=True ) # Initialize Django apps - necessary for AppConfig.ready() to run import django django.setup() print(get_my_settings()) # Expected output will depend on whether MYAPP_SETTING_1 is overridden in global settings or by the environment variable.
Debug
Known issues
gotchaAppConf subclasses must be imported during Django's startup phase for settings to be correctly applied. The official documentation recommends placing `AppConf` subclasses in `models.py` or importing them via the `ready()` method of your application's `AppConfig` class.
fix
Place your `AppConf` subclass in your app's `models.py` or, for a cleaner separation, import it from within your `AppConfig`'s `ready()` method (e.g., `from . import conf`).
affects: All versions
gotchaDo not confuse `django-appconf` with Django's built-in `AppConfig` class (from `django.apps`). They serve different purposes: `django-appconf` manages application-specific settings and defaults, while `AppConfig` stores metadata for an application within Django's app loading mechanism. They are not interchangeable.
fix
Understand that `django-appconf` provides a structured way to handle defaults for `django.conf.settings`, separate from `django.apps.AppConfig`'s role in app metadata and lifecycle hooks.
affects: All versions
gotchaWhen defining a `configure_<setting_name>` method within your `AppConf` subclass for custom logic, always ensure the method explicitly returns a value. Forgetting to return a value will result in the setting effectively becoming `None`.
fix
Verify that all `configure_<setting_name>` methods include a `return` statement at the end of their logic.
affects: All versions
deprecatedThe `app_label` attribute within the inner `Meta` class of `AppConf` was renamed to `prefix` in version 0.4. While older versions might have offered backward compatibility, for current versions (>=1.0), `prefix` should be used to explicitly define the setting prefix.
fix
Always use `prefix = 'YOUR_PREFIX'` within the `Meta` class of your `AppConf` subclass instead of `app_label`.
affects: <=0.3
Errors
Common errors & fixes
django.core.exceptions.ImproperlyConfigured: Requested setting XXX, but settings are not configured.
This error occurs because django-appconf relies on Django's settings being fully initialized. If your AppConf subclass is imported in a module that loads before Django's settings are configured (e.g., outside of models.py), it will attempt to access uninitialized settings.
fix
Ensure your AppConf subclass is defined in your Django application's `models.py` file. Django guarantees that `models.py` is imported during its startup process, ensuring that settings are configured when your AppConf class is processed.
NameError: name 'settings' is not defined
This error arises when you try to access `django.conf.settings` in a context where it has not yet been imported or made available, often in modules that are loaded very early in the Django startup sequence before `django.conf.settings` is ready.
fix
To resolve this, ensure that `from django.conf import settings` is present in the file where you are attempting to access `settings`. If this occurs during app loading, move your `AppConf` definition to `models.py` as it's guaranteed to be loaded after Django's settings are configured.
AttributeError: 'Settings' object has no attribute 'MYAPP_SETTING_NAME'
This typically means that a setting defined in your AppConf subclass is not being found. This can happen if the AppConf class itself hasn't been properly loaded by Django, if you're trying to access a setting without the correct prefix (e.g., 'MYAPP_'), or if you expect unprefixed access directly from the AppConf instance but haven't enabled proxying.
fix
Verify that your AppConf subclass is correctly placed (e.g., in `models.py`) to ensure it's loaded during Django's startup. When accessing settings via `django.conf.settings`, use the capitalized app label as a prefix (e.g., `settings.MYAPP_MY_SETTING`). If you wish to access settings directly from an instantiated AppConf object without a prefix and have it proxy to `django.conf.settings`, set `class Meta: proxy = True` in your AppConf subclass.
ImportError: cannot import name 'AppConf'
This error indicates that the `AppConf` class cannot be found. This usually happens if the `django-appconf` package is not installed in your Python environment or if there is a typo in the import statement.
fix
First, ensure `django-appconf` is installed by running `pip install django-appconf`. Then, verify that the import statement is `from appconf import AppConf` in your code.
Upgrade
Version history
1.2.0latest on PyPI · released Nov 8, 2025
Audit
Dependencies
DjangorequiredThis is a Django-specific library.
Agent activity
50 hits · last 30 days
node
44
OpenAI (training)
1
Resources
django-appconf — pip install django-appconf · libregistry