django-hosts Documentation

If you want to avoid adding {% load hosts %} to every template, you can globally override Django's built-in url tag. This is particularly useful for ensuring compatibility with 3rd party apps that use the standard url tag but need to respect your host configurations.

To do this, add 'django_hosts.templatetags.hosts_override' to your TEMPLATES configuration under OPTIONS['builtins'].

# settings.py
TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'builtins': [
                'django_hosts.templatetags.hosts_override',
            ],
        },
    },
]

To use django-hosts alongside Django Debug Toolbar, you must ensure the middleware order is correct. The debug_toolbar.middleware.DebugToolbarMiddleware must be placed after django_hosts.middleware.HostsRequestMiddleware and before django_hosts.middleware.HostsResponseMiddleware in your MIDDLEWARE setting. Additionally, you must be using django-debug-toolbar version 0.9.X or higher.

MIDDLEWARE = [
    "django_hosts.middleware.HostsRequestMiddleware",
    # your other middlewares..
    "debug_toolbar.middleware.DebugToolbarMiddleware",
    "django_hosts.middleware.HostsResponseMiddleware",
]

Install the package using pip:

pip install django-hosts

To route requests to different URL configurations based on the hostname, define host_patterns in a dedicated module. Use patterns() to group host definitions and host() to define specific host matching rules using regular expressions.

Important: Patterns are matched in order. Place more specific patterns (like www) before more general/wildcard patterns (like \w+) to prevent incorrect routing.

from django.conf import settings
from django_hosts import patterns, host

host_patterns = patterns(
    "",
    host(r"www", settings.ROOT_URLCONF, name="www"),
    host(r"(\w+)", "path.to.custom_urls", name="wildcard"),
)

Create a module (e.g., hosts.py) to define how different hosts map to specific URLconf modules. Use patterns() to group host definitions and host() to define individual host mappings.

Key Rules:

• Patterns are evaluated in order.
• The first argument to host() is a regular expression matched against the extreme left of the requested host.
• It is implied that all patterns end with either a literal full stop (.) or an end-of-line metacharacter.
• If no pattern matches, the request falls back to the standard ROOT_URLCONF.

from django_hosts import patterns, host

host_patterns = patterns(
    "path.to",
    host(r"api", "api.urls", name="api"),
    host(r"beta", "beta.urls", name="beta"),
)

You can control the default scheme used by the host_url template tag by setting HOST_SCHEME in your Django settings.

• The default behavior is to use // (protocol-relative).
• You can change this to a specific scheme like https globally.

# settings.py
HOST_SCHEME = 'https'

Add the following settings to your settings.py to configure django-hosts behavior:

By default, host_url generates URLs relative to the host pattern. If you want to append a default domain name to all generated URLs, set the PARENT_HOST setting in your Django configuration.

Example: If PARENT_HOST = "example.com", a host pattern for admin will render as //admin.example.com/... instead of just //admin/....

# settings.py
PARENT_HOST = "example.com"

If your pytest tests using client.post(...) are failing after adding django-hosts, it is likely because the request is not being associated with the expected host. To fix this, pass the SERVER_NAME argument to the post call to specify the host that should handle the request.

client.post(..., SERVER_NAME="api-server.something")

You can use regular expressions in the host() function to match multiple subdomains to the same URLconf. For example, to route both foo.example.com and bar.example.com to the same URLconf, use a grouping regex.

from django_hosts import patterns, host

host_patterns = patterns(
    "",
    host(r"(foo|bar)", "path.to.urls", name="foo-or-bar"),
)