Installation and setup

Packages and repositories

This toolkit ships as two separate PyPI packages, each with its own GitHub repository:

Role	Links
Server	django-udp-discovery on PyPI · django-udp-discovery source
Client	django-udp-discovery-client on PyPI · django-udp-discovery-client source

You normally install both packages into the environments that need them (server Django app + any discoverer scripts or Django projects).

Requirements

Python: django-udp-discovery supports Python 3.7+; the client targets 3.8+. Prefer 3.8+ for both together.
Django: required on servers (django-udp-discovery). Optional on clients except for python manage.py discover_servers, which needs Django and discovery_client_django.
Network extras (client): Broad discovery relies on netifaces or ifaddr (see pip install django-udp-discovery-client[network]). Without either, discover() logs an ImportError and returns [].
Server platform: upstream documents Linux and Windows; macOS is not supported for django-udp-discovery.

Install from PyPI (recommended)

Latest published releases:

pip install django-udp-discovery
pip install "django-udp-discovery-client[network,django]"

The client line enables interface enumeration (``network``) and Django integration (``django``) for the discover_servers command.

Install from each Git clone

Pick the repo you need, clone it, install from its root (editable optional).

Server

git clone https://github.com/Ogro-Projukti/django-udp-discovery.git
cd django-udp-discovery
pip install .

django-udp-discovery sources live under src/django_udp_discovery; Hatch builds that layout automatically.

Client

git clone https://github.com/Ogro-Projukti/django-udp-discovery-client.git
cd django-udp-discovery-client
pip install .
pip install ".[network]"
pip install ".[django]"          # optional, for ``discover_servers``

Use "[all]" if you prefer one command for extras.

Build these docs locally (toolkit repository only)

This repo can hold documentation only. It does not vendor the libraries; Sphinx imports them after you install from PyPI (same set Read the Docs uses):

pip install -r docs/requirements.txt

That installs Sphinx, django-udp-discovery, django-udp-discovery-client[django], ifaddr (lightweight imports for autodoc), and the HTML theme. Then:

python -m sphinx -b html docs docs/_build/html

If you keep a local packages/ directory for reading upstream source, list it in .gitignore and do not rely on it for builds.

Django settings checklist

Server project

Add the app and run Django:

INSTALLED_APPS = [
    # ...
    "django_udp_discovery",
]

Optional tuning (see Server package: django-udp-discovery):

DISCOVERY_PORT = 9999
DISCOVERY_MESSAGE = "DISCOVER_SERVER"
RESPONSE_PREFIX = "SERVER_IP:"
ENABLE_LOGGING = True

Server debugging and console logging

ENABLE_LOGGING toggles informational output inside django_udp_discovery, but Django still needs a `LOGGING` configuration before records reach handlers. The snippet below matches the `django-udp-discovery` package README (Debugging and Console Logging): add it, or merge the loggers entry, into your settings.py.

See also Logging in the Django documentation.

Note

This subsection mirrors upstream server docs: Debugging and Console Logging in the django-udp-discovery repository.

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '{levelname} {asctime} {module} {message}',
            'style': '{',
        },
        'simple': {
            'format': '{levelname} {message}',
            'style': '{',
        },
    },
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'formatter': 'simple',
        },
    },
    'loggers': {
        'django_udp_discovery': {
            'handlers': ['console'],
            'level': 'DEBUG' if DEBUG else 'INFO',
            'propagate': False,
        },
    },
}

With this in place you should see, on the console, details such as:

listener startup / shutdown events
discovery UDP requests received at the probe port
successful replies emitted back to callers
port binding conflicts and unexpected socket faults
other state transitions emitted by django_udp_discovery

The DEBUG versus INFO split follows Django’s DEBUG flag (DEBUG=False collapses chatter to informational messages only).

Client-only Django project (management command)

INSTALLED_APPS = [
    # ...
    "discovery_client_django",
]

Core Python discovery does not require Django. Client logging mirrors the standalone package README: configure the `django_udp_discovery_client` logger if you integrate it into Django’s LOGGING tree.

Firewalls and ports

UDP incoming on the server must reach the Django process (default 9999).
Answers are sent directly back to the sender’s socket; firewall rules must allow that return traffic.
Discovery does not expose HTTPS/HTTP ports; clients still need the real app port afterward (often 8000, see protocol notes in Quickstart: working in five minutes).

Verifying

Server: run Django; confirm UDP starts without binding errors logged by django_udp_discovery.
Client: python -c "from discovery_client import discover; print(discover())" or python manage.py discover_servers.

See Quickstart: working in five minutes for the shortest end-to-end path.