A Self-Hosted File Manager designed for seamless file sharing, with built-in support for client apps like ShareX, Flameshot, iOS and Android.

🚀 Currently in Active Development – Expect breaking changes until an official major version release.

🔹 Have an idea? Submit a [Feature Request](https://github.com/django-files/ 🐛 Found a bug? Report an Issue for any bugs.

• Overview
• Running
  • Docker Run
  • Docker Compose
• Features
• Screen Shots
• Usage
  • Files
  • Short URL
  • User Settings
  • Site Settings
• Variables
• Database
• Dev Deploy
• Frameworks

Django Files is a Django-based web application with a Celery task queue, built using Bootstrap 5.3 and containerized with Docker. It enables file uploads via API or UI using Uppy, offering a robust and flexible self-hosted solution for file management.

⚠️ Important Notice

🔸 This project is in Beta – Expect breaking changes without migrations. 🔸 If not using S3, you must mount media_dir to /data/media for file storage and SQLite database persistence.

For Extra Options See: Variables

You should override the default credentials with environment variables or settings.env. You will be prompted to set your password on first login.

Short one-liner to run in foreground:

docker run --rm -p 80:80 -v ./django-files:/data/media ghcr.io/django-files/django-files:latest

Run it in the background:

docker run --name "django-files" -d --restart unless-stopped  \
  -p 80:80  -v ./django-files:/data/media  \
    ghcr.io/django-files/django-files:latest

Or Manually Specify a Username and Password:

docker run --name "django-files" -d --restart unless-stopped  \
  -p 80:80  -v ./django-files:/data/media  \
  -e USERNAME=cooluser  \
  -e PASSWORD=secretpassword  \
    ghcr.io/django-files/django-files:latest

version: '3'

services:
  django-files:
    environment:
      USERNAME: 'cooluser'
      PASSWORD: 'secretpassword'
    image: ghcr.io/django-files/django-files:latest
    volumes:
      - media_dir:/data/media
    ports:
      - '80:80'

volumes:
  media_dir:

Then Finally:

nano docker-compose.yaml # write your compose file
docker compose up --remove-orphans --force-recreate --detach

For a Docker Swarm and Traefik example, see: docker-compose-prod.yaml

Django Files is packed with features for seamless file management and sharing. More features are in progress! Request a Feature.

• Local or S3 storage support
• One-click integration with ShareX, Flameshot
• iOS Client
• Android Client
• Customizable UI with light/dark mode
• OAuth support (Discord, GitHub, Google) & two-factor authentication (Duo)
• Web extensions for Chrome and Firefox
• Public upload support (optional)

• Multi-user support with local & OAuth authentication options
• Invite system for user onboarding
• OAuth configuration via Django Admin (no restart required)

• Drag & Drop file uploads
• Short URLs with vanity support
• Private & password-protected files
• Configurable EXIF metadata removal on upload
• Bulk file actions
• Albums & galleries for organizing files

• Dashboard with user-friendly overview & stats
• Graph-based analytics (work in progress)
• File expiration & view counting

• Firefox Extension:https://addons.mozilla.org/addon/django-files
• Chrome Extension: https://chrome.google.com/webstore/detail/django-files/abpbiefojfkekhkjnpakpekkpeibnjej

Screenshots and UI previews are available on the Django Files Github Site. from the menu.

Django Files is backwards compatible with Zipline client upload settings.

Upload Endpoint: /api/upload/
Response Type: JSON

{
  "files": ["full-url"],
  "url": "full-url",
  "name": "file-name",
  "size": "size-bytes"
}

Upload Endpoint: /api/shorten/
Response Type: JSON

{
  "url": "full-short-url"
}

You can parse the URL with JSON keys url or Zipline style files[0]

• Avatar: Can be reuploaded if set to Local/Cloud.
• Avatar Source: If to use oauth avatars, or local avatars. (Oauth avatars cannot be changed via django files.)
• First Name: User's first name, for personalization of username display.
• Timezone: User's timezone, will show times in user's local time when logged in.
• Default Expire: The default file expiration for files uploaded with out an expiration for this user.
• Default Upload Format: The default file name format for files uploaded without a specific file name format.
• Strip All EXIF Data: Strips all EXIF metadata from images on upload. (Changes do not apply to existing uploads)
• Strip GPS EXIF Data: Strips GPS meta data from images on upload. (Changes do not apply to existing uploads)
• Private Files: Make uploads private by default unless otherwise specified. (Changes do not apply to existing uploads)
• Password Protected File: Make uploads password protected by default unless otherwise specified. (Changes do not apply to existing uploads)
• Enabled EXIF Embeds: If to show EXIF metadata on unfurls/embeds.
• Appearance Embed Color: Color of embeds/unfurls for shared links.
• Appearance Nav Colors: Color of navbar for this user and anonymous users viewing shared user files.
• Discord Webhooks: Discord webhooks to trigger when a file is uploaded.

• Site URL: The site url to use, used to generate links.
• Site Title: Site title in browser and unfurls.
• Global Storage Quota: The storage quota for the entire django files deployment.
• User Default Storage Quota: The default storage quota for new users without a specified quota.
• Timezone: global timezone for django files deployment. Default TZ anonymous users see.
• Site Description: Site description shown on unfurled links for clients that show url unfurls.
• Public Uploads: /public : When enabled anonymous users can upload.
• Oauth Registration: When enabled ANY user may sign up via oauth login.
• Local Authentication: When disabled, only oauth authentication can be performed. (Falls back to enabled when oauth not configured)

Important

NO VARIABLES ARE REQUIRED! All are optional.

OAuth may be configured from the UI.
AWS/Duo/Sentry require environment variables. Switching between local storage and s3 is not supported and WILL cause problems.

• sqlite3 - default - zero configuration, works out of the box
• mysql - must set up and maintain your own database
• postgresql - must set up and maintain your own database

Note: sqlite3 is stored by default in media_dir/db based on what is set in the docker-compose.yaml file.

Command included below to generate the required SECRET.
The SITE_URL should be set with a variable for development, in UI Settings. You may also want to configure an auth method from the variables above.

git clone https://github.com/django-files/django-files
cd django-files
cp settings.env.example settings.env

cat /dev/urandom | tr -dc 'A-Za-z0-9' | head -c 50
# copy above output for SECRET variable, add to settings or as environment variable
vim settings.env

docker compose up --build --remove-orphans --force-recreate --detach
# or
docker compose -f docker-compose-dev.yaml up --build --remove-orphans --force-recreate -detach
docker compose logs -f

# bring the stack down
docker compose down --remove-orphans

Auto restarting dev deployment using settings.env for config. (ctrl+c to restart, double ctrl+c to exit)

_file="docker-compose-dev.yaml";while true;do docker compose -f "${_file}" down --remove-orphans;sep 10;docker compose -f "${_file}" up --build --remove-orphans -d --force-recreate;docker compose -f "${_file}" logs -f;echo sleep 1;sleep 1;done

• Python
• Django
• Celery
• Font Awesome
• Bootstrap
• Uppy
• Highlight.js
• Datatables
• Swagger

Feature Requests | Issues