Install & Compatibility
Where this runs
tested against v9.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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 144.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 11.3s · import 0.000s · 154MB
143MB installed
● package 143MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ESIClientProvider
✓ from esi import ESIClientProvider
✗ from esi import ESIClientProvider
This quickstart demonstrates how to set up `django-esi` in a minimal Django context, instantiate the `ESIClientProvider`, and make a simple request to a public ESI endpoint (e.g., fetching EVE Universe type information). It highlights the importance of `compatibility_date`, User-Agent information, and optional tag/operation filtering for memory optimization. Note that `ESI_SSO_CLIENT_ID`, `ESI_SSO_CLIENT_SECRET`, and `ESI_SSO_CALLBACK_URL` are generally required settings even if not directly used in a public endpoint call.
import os
from django.conf import settings
# Minimal Django settings for standalone execution (in a real project, these would be in settings.py)
if not settings.configured:
settings.configure(
INSTALLED_APPS=['esi'],
SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-dev'),
# Required for EVE SSO, even if not used in this specific public API example
ESI_SSO_CLIENT_ID=os.environ.get('ESI_SSO_CLIENT_ID', 'test-dummy'),
ESI_SSO_CLIENT_SECRET=os.environ.get('ESI_SSO_CLIENT_SECRET', 'test-dummy'),
ESI_SSO_CALLBACK_URL=os.environ.get('ESI_SSO_CALLBACK_URL', 'http://localhost:8000/sso/callback'),
ESI_USER_CONTACT_EMAIL=os.environ.get('ESI_USER_CONTACT_EMAIL', 'your_email@example.com'),
DEBUG=True # Useful for development, disables some client filters
)
from esi.openapi_clients import ESIClientProvider
# Instantiate the ESI client provider
# It's strongly recommended to re-use this client wherever possible (e.g., as a global or singleton).
# For best results, use a compatibility_date that you genuinely tested against.
# ua_appname should be PascalCase and ua_version semantic versioning.
# For development, you can set DEBUG=True in Django settings to temporarily bypass tag/operation filtering.
esi_client = ESIClientProvider(
compatibility_date="2024-07-23",
ua_appname="MyDjangoApp",
ua_version="0.1.0",
# Filtering is crucial for memory efficiency in production
# Example: operations=["GetAlliances"], tags=["Universe"]
tags=["Universe"]
)
# Example: Fetching a EVE Universe type (e.g., for 'Vexor')
try:
# Using the filtered client to access the Universe tag
type_id = 603
vexor_info = esi_client.client.Universe.GetUniverseTypesTypeId(type_id=type_id).results()
print(f"Fetched EVE Type (ID: {type_id}): {vexor_info.name}")
# Example of localized response
vexor_info_ko = esi_client.client.Universe.GetUniverseTypesTypeId(
type_id=type_id, Accept_Language='ko'
).results()
print(f"Fetched EVE Type in Korean (ID: {type_id}): {vexor_info_ko.name}")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe OpenAPI client introduced in Django-ESI 8.x can consume significantly more memory due to in-memory Pydantic models. Failing to use `operations` or `tags` filters when instantiating `ESIClientProvider` without `DEBUG=True` will result in an `AttributeError`.fixWhen creating `ESIClientProvider`, always specify `operations` (list of endpoint names) or `tags` (list of ESI tags, e.g., 'Universe', 'Alliance') to load only the necessary API parts. In `settings.DEBUG=True`, this check is bypassed, and a warning is logged instead.
affects: 8.x and later
gotchaThe `compatibility_date` parameter for `ESIClientProvider` should be set to a date you genuinely tested your application against, not 'today'. This header dictates ESI's API behavior for your application.fixChoose a `compatibility_date` (YYYY-MM-DD format) that corresponds to when you last verified your ESI integration. Updating Django-ESI itself does not require changing this date unless you are re-testing against newer ESI specifications.
affects: All versions using `ESIClientProvider`
gotchaDjango-ESI 8.x and later heavily rely on caching and E-Tags. Disabling this can lead to excessive ESI requests and higher memory usage for your application if not managed carefully.fixAdhere to the default caching and E-Tag behavior. If disabling `ESI_CACHE_RESPONSE` (by setting to `False`) or custom caching, ensure you understand the implications for ESI rate limits and your application's resource consumption.
affects: 8.x and later
breakingEVE SSO and User-Agent settings are mandatory for `django-esi` to function correctly and adhere to CCP's developer guidelines.fixEnsure the following settings are correctly configured in your `settings.py`: `ESI_SSO_CLIENT_ID`, `ESI_SSO_CLIENT_SECRET`, `ESI_SSO_CALLBACK_URL`, and `ESI_USER_CONTACT_EMAIL`. The contact email is included in the `User-Agent` header for all requests.
affects: All versions
Upgrade
Version history
9.5.0latest on PyPI · released Jun 9, 2026
Audit
Dependencies
DjangorequiredCore framework dependency for a Django application.
aiopenapi3requiredUnderlying OpenAPI 3 client library for ESI interactions.