Registry /
azure / azure-appconfiguration-provider
Install & Compatibility
Where this runs
tested against v2.5.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
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.666s · 97.3MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 3.2s · import 0.601s · 29MB
55MB installed
● package 55MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
load
✓ from azure.appconfiguration.provider import load
✗ from azure.appconfiguration.provider.AzureAppConfigurationProvider import load_provider
In version 2.0.0, the `load_provider` class method was replaced by the module-level `load` function for loading configurations.
SettingSelector
✓ from azure.appconfiguration.provider import SettingSelector
Used to select specific key-value pairs based on key and label filters.
WatchKey
✓ from azure.appconfiguration.provider import WatchKey
Used to specify a key to monitor for changes, triggering dynamic refresh.
DefaultAzureCredential
✓ from azure.identity import DefaultAzureCredential
Standard Azure SDK credential for authenticating with Azure Active Directory.
This quickstart demonstrates how to connect to Azure App Configuration using Azure Active Directory, load configurations (including using `SettingSelector` for filtering), and access values like a dictionary. It also shows how to enable and check feature flags. Ensure `AZURE_APPCONFIG_ENDPOINT` is set as an environment variable and the executing principal has 'App Configuration Data Reader' role.
import os
from azure.appconfiguration.provider import load, SettingSelector
from azure.identity import DefaultAzureCredential
# Set your App Configuration endpoint as an environment variable, e.g., AZURE_APPCONFIG_ENDPOINT
endpoint = os.environ.get("AZURE_APPCONFIG_ENDPOINT", "")
if not endpoint:
print("Please set the AZURE_APPCONFIG_ENDPOINT environment variable.")
exit(1)
try:
# Authenticate with Azure Active Directory (recommended)
# Ensure your principal (user/service principal) has 'App Configuration Data Reader' role.
credential = DefaultAzureCredential()
# Load configuration from Azure App Configuration
# By default, loads all configurations with no label.
config = load(
endpoint=endpoint,
credential=credential,
# Example: Load 'TestApp:Settings:Message' and 'TestApp:Settings:FeatureX' with label 'prod'
# and all configs with no label, with 'prod' taking precedence.
selectors=[
SettingSelector(key_filter="TestApp:Settings:*", label_filter="prod"),
SettingSelector(key_filter="*", label_filter="\0") # '\0' represents no label
],
# Enable feature flags loading
feature_flags_enabled=True
)
print(f"Loaded configuration: ")
for key, value in config.items():
print(f" {key}: {value}")
# Access configuration values like a dictionary
message = config.get("TestApp:Settings:Message", "Default message")
print(f"\nMessage from App Configuration: {message}")
# Check a feature flag
if config.get("TestApp:Settings:FeatureX", False):
print("FeatureX is enabled.")
else:
print("FeatureX is disabled.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe `load_provider` class method was replaced by a module-level `load` function in version 2.0.0. Code using `AzureAppConfigurationProvider.load_provider(...)` will break.fixUpdate imports and function calls from `from azure.appconfiguration.provider.AzureAppConfigurationProvider import AzureAppConfigurationProvider` and `AzureAppConfigurationProvider.load_provider(...)` to `from azure.appconfiguration.provider import load` and `load(...)` respectively.
affects: >=2.0.0
breakingIn version 2.0.0, the handling of `AzureAppConfigurationKeyVaultOptions` changed. The `secret_clients` parameter was removed, and `client_configs` should be used instead, mapping endpoints to client configurations.fixAdjust `AzureAppConfigurationKeyVaultOptions` initialization to use `client_configs` instead of `secret_clients` when resolving Key Vault references.
affects: >=2.0.0
gotchaDynamic refresh of configurations requires both setting `refresh_on` (with `WatchKey`) and explicitly calling the `config.refresh()` method. Simply setting `refresh_interval` without `refresh_on` or calling `refresh()` will not update configurations.fixImplement periodic calls to `config.refresh()` in your application loop or background task, and specify a `WatchKey` in the `refresh_on` parameter during `load()` to trigger refreshes based on changes to a sentinel key.
affects: All versions with dynamic refresh support (>=1.1.0b1).
gotchaRefreshing feature flags and regular configuration settings are independent. Enabling `feature_flags_enabled` allows feature flag refresh, but a change in a feature flag will not automatically trigger a refresh of other configuration settings, and vice-versa.fixIf dynamic refresh is desired for both, configure `refresh_on` keys to monitor changes relevant to both types of settings, or implement separate logic if their refresh triggers differ.
affects: All versions with dynamic refresh support (>=1.1.0b1).
gotchaResolving Key Vault references requires providing separate Azure Active Directory credentials that have access to the Key Vault. The credentials used to access App Configuration are not automatically used for Key Vault.fixWhen calling `load()`, ensure to provide appropriate `keyvault_credential` (e.g., another `DefaultAzureCredential` instance) that has 'Secrets Reader' permissions on the linked Key Vault.
affects: All versions with Key Vault reference support.
gotchaWhen using multiple `SettingSelector` objects, the order in which they are provided to the `selectors` parameter matters. Later selectors in the list will override values from earlier selectors if duplicate keys are found.fixCarefully order your `SettingSelector` list, placing selectors for higher-priority configurations (e.g., environment-specific overrides) later in the list.
affects: All versions with `SettingSelector` support.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.appconfiguration.provider'
The 'azure-appconfiguration-provider' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install azure-appconfiguration-provider'.
ImportError: cannot import name 'load' from 'azure.appconfiguration.provider'
The 'load' function is not available in the 'azure.appconfiguration.provider' module, possibly due to an incorrect import statement or version mismatch.
fixEnsure the correct import statement: 'from azure.appconfiguration.provider import load'.
TypeError: load() got an unexpected keyword argument 'connection_string'
The 'load' function does not accept 'connection_string' as a keyword argument, indicating a possible version mismatch or incorrect usage.
fixUse the correct parameters for the 'load' function as per the library's documentation.
AttributeError: module 'azure.appconfiguration.provider' has no attribute 'load'
The 'load' function is not found in the 'azure.appconfiguration.provider' module, possibly due to an outdated or incorrect version of the package.
fixUpdate the package to the latest version using pip: 'pip install --upgrade azure-appconfiguration-provider'.
ValueError: Invalid connection string
The provided connection string is malformed or contains incorrect information.
fixVerify and correct the connection string format as per the Azure App Configuration documentation.
Upgrade
Version history
2.5.0latest on PyPI · released May 26, 2026
Audit
Dependencies
pythonrequiredRequired Python version
azure-identityoptionalRecommended for Azure Active Directory authentication, which is the preferred method for connecting to Azure services.