Django Appointment 📦
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 📚
- 📖 Documentation site: why you'd use the app, its features, and every configuration option.
- 🧭 Tutorial: a step-by-step walkthrough of a working setup.
- 📝 Release notes: on the documentation site,
the GitHub releases page, and, for older versions, in
docs/release_notes. - 🕰️ Features added in earlier versions:
docs/history.
⚠️ 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 ✨
- Customizable time slots, lead time (when bookings open each day) and finish time (when they close).
- Conflict and availability handling, so clients are only offered slots that are free.
- Integration with the Django admin.
- Dedicated staff pages to manage appointments, staff members, services, working hours, days off and conflicts.
- A friendly booking page where clients see the free slots and book one.
- 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.
- Clients can reschedule their appointment, if you allow it.
- Custom templates: replace the default pages and emails with your own designs. See the custom templates guide.
- Slots that account for the real length of each service, plus an optional rest time between appointments (for everyone or per staff member).
- Automatic cleanup of abandoned booking requests, also available as the
cleanup_appointment_requestsmanagement command. - 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.
-
Install the package:
pip install django-appointment
-
Add
appointmenttoINSTALLED_APPSin yoursettings.py:INSTALLED_APPS = [ # other apps 'appointment', ]
-
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')), ]
-
(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.
-
Create and apply the migrations:
python manage.py makemigrations appointment python manage.py migrate
-
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). -
Create at least one service. Use a price of
0if it's free. A description and an image are optional. -
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/.
-
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
-
Install Django Q:
pip install django-q2
-
Add
django_qtoINSTALLED_APPSin yoursettings.py:INSTALLED_APPS = [ # ... 'django_q', ]
-
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
-
Create Django Q's tables:
python manage.py migrate
-
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_requestsyourself.
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:
customMetaTaggoes inside<head>: the staff pages put the CSRF token there for their AJAX requests.customCSSandcustomJSlet the app add its styles and scripts.bodyis 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.titleanddescriptionare 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.
-
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
-
Create a
.envfile 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
.envfile holds secrets. Don't commit it. -
Build and start the containers:
docker compose up -d --build
On older Docker installs, use
docker-compose(with a hyphen) instead ofdocker composein every command. -
Create and apply the migrations:
docker compose exec web python manage.py makemigrations appointment docker compose exec web python manage.py migrate
-
Create a superuser to log in to the Django admin:
docker compose exec web python manage.py createsuperuser
-
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.
-
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
Dockerfileanddocker-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
Metadata
Release files for django-appointment 3.13.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_appointment-3.13.1.tar.gz | 567.6 kB | Without provenance | Details for django_appointment-3.13.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_appointment-3.13.1-py3-none-any.whl | Python 3 | none | any | Details for django_appointment-3.13.1-py3-none-any.whl |
Total release size: 1.2 MB
Release files / django_appointment-3.13.1.tar.gz
| Download URL | django_appointment-3.13.1.tar.gz |
|---|---|
| Size | 567.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
757cb0fdb6270f51a1549ea95e4bf5b7a97868e5b11017acbb35f634d14ba35e
|
|
BLAKE2b-256 checksum How to use checksums |
0b581d92b97bd12fc57a44d90d1314457d4b7d7370544352d61297dfd6cda99b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.1
|
Release files / django_appointment-3.13.1-py3-none-any.whl
| Download URL | django_appointment-3.13.1-py3-none-any.whl |
|---|---|
| Size | 623.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
29ba667a9d246f187bdc9b686d2324b2b13bd89860bad945d124a277b0d0e786
|
|
BLAKE2b-256 checksum How to use checksums |
a0213e86bc7f781e7d4e747c94c81a090ff310ef1473d33e730624a104e7d18c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.1
|
Security for django-appointment 3.13.1
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.