Install & Compatibility
Where this runs
tested against v2.7.2 · 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 · 66.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 0.000s · 67MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
django_cotton
✓ INSTALLED_APPS = ['django_cotton', ...]
Add 'django_cotton' to your Django project's INSTALLED_APPS in settings.py. This usually handles automatic loader and templatetag configuration.
1. Add `django_cotton` to your `INSTALLED_APPS` in `settings.py`. This typically configures the necessary template loaders automatically. 2. Create a `cotton` directory within your Django app's `templates` folder or a project-level `templates` folder. 3. Define a component, for example, `button.html`, inside the `cotton` directory. The `{{ slot }}` variable renders any content passed between the component's opening and closing tags. 4. Use the component in your main Django templates using the HTML-like `c-` prefixed tag and kebab-case naming.
<!-- settings.py -->
INSTALLED_APPS = [
# ... other apps
'django_cotton',
]
# Optional: Manual TEMPLATES configuration if you have custom loaders
# TEMPLATES = [
# {
# 'BACKEND': 'django.template.backends.django.DjangoTemplates',
# 'DIRS': [],
# 'APP_DIRS': False, # Set to False if DIRS is used for project-level templates
# 'OPTIONS': {
# 'loaders': [
# ('django.template.loaders.cached.Loader', [
# 'django_cotton.template.loaders.CottonLoader',
# 'django.template.loaders.filesystem.Loader',
# 'django.template.loaders.app_directories.Loader',
# ]),
# ],
# 'builtins': [
# 'django_cotton.templatetags.cotton',
# ],
# },
# },
# ]
# --- In your templates directory (e.g., myproject/templates/cotton/button.html) ---
<button class="p-2 rounded-md bg-blue-500 text-white hover:bg-blue-600">
{{ slot }}
</button>
# --- In a main Django template (e.g., myproject/templates/index.html) ---
<h1 class="text-2xl font-bold">Welcome!</h1>
<c-button>Click Me</c-button>
<c-button class="bg-green-500 hover:bg-green-600">Submit</c-button>
Debug
Known issues
breakingInternal template tag names changed in version 2.4.0. While these were not officially documented for external use, direct reliance on previous internal tag names would break upon upgrade.fixReview any custom code that might have directly referenced internal Django Cotton template tags. Migrate to documented public APIs or the HTML-like component syntax.
affects: >=2.4.0
gotchaIf your project uses a custom `TEMPLATES` loader configuration, automatic setup by adding 'django_cotton' to `INSTALLED_APPS` might be insufficient. You may need to manually configure the `CottonLoader`.fixExplicitly add `django_cotton.template.loaders.CottonLoader` to your `TEMPLATES` `OPTIONS.loaders` list, ideally wrapped by `django.template.loaders.cached.Loader` for optimal performance.
affects: All versions
gotchaComponents are referenced in templates using kebab-case (e.g., `<c-my-component />`), but component filenames typically use snake_case by default (e.g., `my_component.html`). This naming convention difference can sometimes be a source of confusion.fixBe mindful of the casing convention. You can configure `COTTON_SNAKE_CASED_NAMES = False` in `settings.py` to allow kebab-case filenames for components if preferred.
affects: All versions
gotchaIn some setups, particularly older ones or with specific environment configurations, the HTML-like component syntax (`<c-component />`) might render as raw HTML in the browser rather than being processed by Django Cotton. The native `{% cotton %}` tag typically still works in such cases.fixEnsure `django_cotton` is correctly listed in `INSTALLED_APPS` and that the template loader configuration is valid. If using manual loader setup, double-check its correctness. If issues persist, consider using the native `{% cotton %}` tag as an alternative. affects: Potentially all, more common in older versions or misconfigurations
Upgrade
Version history
2.7.2latest on PyPI · released Jun 1, 2026
Audit
Dependencies
DjangorequiredDjango Cotton is a Django-specific library and requires a compatible Django version.
PythonrequiredRequires Python 3.8 or newer, but less than 4.