Skip to main content

Django Appointment 📦

Tests Published on PyPi Doc Current Release Version pypi Version PyPi downloads License GitHub commit activity GitHub last commit GitHub issues GitHub pull requests GitHub contributors GitHub stars Django compatible version Python compatible version Latest on Django Packages

Django-Appointment is a Django app for booking appointments. You choose how your days are split into time slots, when bookings open and close, and how much rest staff get between appointments, or you keep the defaults. The app handles conflicts and availability for you, so clients only ever see slots that are actually free.

👀 Try the demo first

The quickest way to understand the app is to play with the live demo.

It takes a couple of minutes, and it will make the rest of this README (and the configuration options) much easier to follow. In the demo you can see:

  • 📅 how clients book an appointment,
  • ⚙️ how the admin settings change what clients see,
  • 📧 the email notifications in action,
  • 🔄 how conflicts and availability are handled.

A small favor about emails 🙏

The demo sends real emails. Please use your real email address, or, if you'd rather not share yours or don't care about the emails, use the shared address okfiw@thenightcoders.tech.

Please don't make up an address. Emails sent to addresses that don't exist bounce back, and if too many bounce, email providers like Gmail and Yahoo start treating the demo's mail server as spam. If that happens, I'll have to take the demo offline for everyone. I keep an eye on those bounces, so thank you for helping keep the demo up!

Your privacy: the demo database is wiped every 2 hours. I don't keep or use your email address.

Please read the terms of use before using the demo.

Documentation 📚

⚠️ Upgrading from a version older than 2.0.0? Version 2.0.0 changed the database a lot. Please read the migration guide before you update. For later versions, see the migration guides folder.

Features ✨

  1. Customizable time slots, lead time (when bookings open each day) and finish time (when they close).
  2. Conflict and availability handling, so clients are only offered slots that are free.
  3. Integration with the Django admin.
  4. Dedicated staff pages to manage appointments, staff members, services, working hours, days off and conflicts.
  5. A friendly booking page where clients see the free slots and book one.
  6. Email notifications:
    • a confirmation email to the client as soon as they book,
    • an optional reminder email 24 hours before the appointment (needs Django Q, see below),
    • an ICS attachment so clients can add the appointment to their calendar.
  7. Clients can reschedule their appointment, if you allow it.
  8. Custom templates: replace the default pages and emails with your own designs. See the custom templates guide.
  9. Slots that account for the real length of each service, plus an optional rest time between appointments (for everyone or per staff member).
  10. Automatic cleanup of abandoned booking requests, also available as the cleanup_appointment_requests management command.
  11. Per-day unavailability: a staff member can block part of a single day (a break, a meeting) without taking the whole day off, and the booking page hides those slots.

Quick Start 🚀

Django-Appointment supports Python 3.11+ and Django 4.2+. See the compatibility matrix for the exact combinations that are tested.

  1. Install the package:

    pip install django-appointment
    
  2. Add appointment to INSTALLED_APPS in your settings.py:

    INSTALLED_APPS = [
        # other apps
        'appointment',
    ]
    
  3. Include the app's URLs in your project's urls.py:

    from django.urls import path, include
    
    urlpatterns = [
        # other urls
        path('appointment/', include('appointment.urls')),
    ]
    
  4. (Optional) Set your website's name in settings.py. It is shown at the top of the emails sent to clients:

    APPOINTMENT_WEBSITE_NAME = 'Chocolates'
    

    You can also set it later from the Django admin, in the app's configuration. The admin value wins over the setting.

  5. Create and apply the migrations:

    python manage.py makemigrations appointment
    python manage.py migrate
    
  6. Start the development server (python manage.py runserver) and log in to the Django admin at http://127.0.0.1:8000/admin/ (the admin app must be enabled).

  7. Create at least one service. Use a price of 0 if it's free. A description and an image are optional.

  8. Add at least one staff member who offers that service, and give them working hours. Without a staff member, the booking page has no slots to show. You can do this from the Django admin or from the staff pages at http://127.0.0.1:8000/appointment/app-admin/user-profile/.

  9. Open http://127.0.0.1:8000/appointment/request/<service_id>/ to see the free slots and book an appointment.

The tutorial walks through these steps with screenshots.

Using a custom user model

You don't need to do anything if you use Django's default user model. If you use your own (AUTH_USER_MODEL = 'client.UserClient', for example), keep in mind that the app creates an account for each new client when they book. It calls your manager's create_user with keyword arguments and no password:

# If your user model has a `username` field:
User.objects.create_user(username=..., email=..., first_name=..., last_name=...)

# Otherwise:
User.objects.create_user(email=..., first_name=..., last_name=...)

So your create_user must accept those arguments and work without a password. Once the booking is done, the client gets an email with a link to set their password.

Email and Django Q Configuration 📧

Email Configuration 📧

The app needs a working email setup to send confirmations and reminders. Add this to your settings.py:

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'your_smtp_host'
EMAIL_PORT = 587  # or 465 with EMAIL_USE_SSL
EMAIL_USE_TLS = True  # or EMAIL_USE_SSL = True
EMAIL_HOST_USER = 'your_email@example.com'
EMAIL_HOST_PASSWORD = 'your_email_password'

# Optional: your website's name, shown at the top of the emails
APPOINTMENT_WEBSITE_NAME = 'Your Website Name'

To change the emails, see Custom templates: each email can be overridden, with its subject and its plain-text part, and with DEBUG = True a superuser can preview them all at app-admin/email-preview/.

Note: In production, keep secrets like the email password in environment variables (or another secure store), not in settings.py.

Django Q Configuration ⏰

Django-Appointment uses Django Q to send reminder emails at the right time and to clean up abandoned booking requests every day. It's optional, but recommended.

Setting up Django Q

  1. Install Django Q:

    pip install django-q2
    
  2. Add django_q to INSTALLED_APPS in your settings.py:

    INSTALLED_APPS = [
        # ...
        'django_q',
    ]
    
  3. Configure Django Q in your settings.py:

    Q_CLUSTER = {
        'name': 'django-appointment',
        'workers': 4,
        'timeout': 90,
        'retry': 120,
        'queue_limit': 50,
        'bulk': 10,
        'orm': 'default',
    }
    USE_DJANGO_Q_FOR_EMAILS = True  # optional: also send all the other emails in the background
    
  4. Create Django Q's tables:

    python manage.py migrate
    
  5. Start the Django Q cluster, and keep it running alongside your server:

    python manage.py qcluster
    

Note: Without Django Q, the app works normally, but reminder emails are not sent and old booking requests are only cleaned up when you run python manage.py cleanup_appointment_requests yourself.

Template Configuration 📝

The app's pages don't come with their own navbar or footer: they render inside your site's base template. Tell the app which template to use in settings.py:

APPOINTMENT_BASE_TEMPLATE = 'base.html'  # used by the booking pages
APPOINTMENT_ADMIN_BASE_TEMPLATE = 'base.html'  # (optional) used by the staff pages, can be a different base

Every page of the app extends appointment/layout.html, which extends the base you set. Your base must include these blocks:

{% block customMetaTag %}
{% endblock %}

{% block customCSS %}
{% endblock %}

{% block title %}
{% endblock %}

{% block description %}
{% endblock %}

{% block body %}
{% endblock %}

{% block customJS %}
{% endblock %}

What each block is for:

  • customMetaTag goes inside <head>: the staff pages put the CSRF token there for their AJAX requests.
  • customCSS and customJS let the app add its styles and scripts.
  • body is where each page's content goes, inside a <div class="djappt"> wrapper. The app's CSS only applies inside that wrapper, so your navbar and footer keep their look.
  • title and description are used for SEO. They're recommended but not required.

Your base must also load jQuery and Bootstrap 5 (CSS and JS) before the customJS block.

Here's an example base.html. It's the one used when you don't set APPOINTMENT_BASE_TEMPLATE.

Customization 🔧

You can change the default values (slot duration, lead time, finish time, and more) in your settings.py, and the app adapts to them. Most of them can also be changed from the Django admin, in the app's configuration, and the admin value wins. The rest time between appointments is only set from the admin, for everyone or per staff member. The full list is in the configuration documentation.

To go further, you can extend the provided models, views and templates, or write your own.

Internationalization 🌍

Django-Appointment is translated and shows dates in the client's language.

Languages:

  • English (en), the default
  • French (fr), maintained by the project
  • Spanish (es), contributed by @alexandermamaniy (new maintainers welcome!)

What you get:

  • 🗣️ The interface translated into 3 languages (more are welcome!)
  • 📅 Localized date formats for 39 languages
  • 🌐 Automatic language detection
  • 📝 Right-to-left (RTL) language support

Quick setup:

# settings.py
USE_I18N = True
LANGUAGES = [('en', 'English'), ('fr', 'French'), ('es', 'Spanish')]

MIDDLEWARE = [
    # ...
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.locale.LocaleMiddleware',  # after SessionMiddleware, before CommonMiddleware
    'django.middleware.common.CommonMiddleware',
    # ...
]

Want to add your language or translate database content? 👉 See the full Internationalization Guide

Docker Support 🐳

The repository comes with a Docker setup to try the app or work on it locally.

Note: This setup is meant for development and local testing, and it runs from a clone of the repository. For production, follow Django's deployment checklist.

  1. Clone the repository and go into it:

    git clone https://github.com/adamspd/django-appointment.git
    # or, with SSH: git clone git@github.com:adamspd/django-appointment.git
    cd django-appointment
    
  2. Create a .env file at the root of the repository. Fill in your own email server's details if you want emails to work:

    # Main admin user. To add more admins, change ADMINS in appointments/settings.py
    ADMIN_NAME="Super Admin"
    ADMIN_EMAIL=super.admin@example.com
    
    # Replace these 3 with your own, otherwise sending emails will fail
    EMAIL_HOST_USER=no-reply@example.com
    EMAIL_HOST_PASSWORD=youcantguessme
    EMAIL_HOST=smtp.example.com
    
    # The default backend, you can leave it as is
    EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
    
    # 587 for TLS. For SSL, use 465 and EMAIL_USE_SSL=True instead
    EMAIL_PORT=587
    EMAIL_USE_TLS=True
    
    # Django Q is already installed in the Docker image. Outside Docker, install django-q2 first
    USE_DJANGO_Q=True
    

    Note: The .env file holds secrets. Don't commit it.

  3. Build and start the containers:

    docker compose up -d --build
    

    On older Docker installs, use docker-compose (with a hyphen) instead of docker compose in every command.

  4. Create and apply the migrations:

    docker compose exec web python manage.py makemigrations appointment
    docker compose exec web python manage.py migrate
    
  5. Create a superuser to log in to the Django admin:

    docker compose exec web python manage.py createsuperuser
    
  6. Open the app at http://localhost:8000 and the Django admin at http://localhost:8000/admin/. From there, add a service and a staff member by following the tutorial.

  7. Stop the containers when you're done:

    docker compose down
    

Note: The Docker setup uses the project's default database (SQLite). To use another database, change the Dockerfile and docker-compose.yml.

Compatibility Matrix 📊

The compatibility matrix shows which versions of Python and Django the package is tested against. It is updated with each round of compatibility tests.

Support 💬

Have a question? Start with the documentation site. If you've found a bug or something isn't clear, please open an issue.

Contributing 🤝

Contributions are welcome! Please read the contributing guidelines to get started.

If you find the project useful, a ⭐ on GitHub would mean a lot. It tells me people are using it and that it's worth keeping it maintained. Thank you!

Code of Conduct 📜

Please read the code of conduct.

Security Policy 🔒

Please read the security policy, especially before reporting a vulnerability.

About the Author

Adams Pierre David - Website

Release files for django-appointment 3.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-appointment 3.14.0
File Size Uploaded Provenance Actions
django_appointment-3.14.0.tar.gz 600.8 kB Without provenance Details for django_appointment-3.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-appointment 3.14.0
File Interpreter ABI Platform Actions
django_appointment-3.14.0-py3-none-any.whl Python 3 none any Details for django_appointment-3.14.0-py3-none-any.whl

Total release size: 1.3 MB

Release files / django_appointment-3.14.0.tar.gz

Download URL django_appointment-3.14.0.tar.gz
Size 600.8 kB
Tags Source
SHA-256 checksum
How to use checksums
13741792f23daa4af8ee87822242fab0c9719eb0afafe952175fc195913e301f
BLAKE2b-256 checksum
How to use checksums
bb4c967bcba9f5d20bd5a2d9f51b0f158a6c6387742510f8a173ec240a02a2c0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / django_appointment-3.14.0-py3-none-any.whl

Download URL django_appointment-3.14.0-py3-none-any.whl
Size 659.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ed843c428cfe4bad4f654539ae6d6f57d0f5487053014ba92fd988e0978ba450
BLAKE2b-256 checksum
How to use checksums
9ae59328b14e4c52a5e2b4a3a4968951774abaf044c3cc7b3e6622083707098e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Security for django-appointment 3.14.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.14.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page