https://github.com/django-files/django-files
Feature Packed Self-Hosted File Sharing
https://github.com/django-files/django-files
django files flameshot flameshot-uploader python python3 sharex sharex-server
Last synced: 2 days ago
JSON representation
Feature Packed Self-Hosted File Sharing
- Host: GitHub
- URL: https://github.com/django-files/django-files
- Owner: django-files
- Created: 2023-07-31T01:51:29.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2026-05-17T02:48:43.000Z (about 1 month ago)
- Last Synced: 2026-05-17T03:39:37.858Z (about 1 month ago)
- Topics: django, files, flameshot, flameshot-uploader, python, python3, sharex, sharex-server
- Language: Python
- Homepage: https://django-files.github.io
- Size: 8.7 MB
- Stars: 11
- Watchers: 3
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://github.com/django-files/django-files/actions/workflows/ci.yaml)
[](https://github.com/django-files/django-files/actions/workflows/test.yaml)
[](https://github.com/django-files/django-files/actions/workflows/lint.yaml)
[](https://app.codacy.com/gh/django-files/django-files/dashboard)
[](https://app.codacy.com/gh/django-files/django-files/dashboard)
[](https://sonarcloud.io/summary/new_code?id=django-files_django-files)
[](https://github.com/django-files/django-files/releases/latest)
[](https://github.com/django-files/django-files)
[](https://github.com/django-files/django-files/graphs/commit-activity)
[](https://github.com/django-files/django-files/stargazers)
[](https://django-files.github.io/)
[](https://github.com/django-files/django-files?tab=readme-ov-file#readme)
# Django Files
A Self-Hosted File Manager designed for seamless file sharing, with built-in support for client apps like ShareX, Flameshot, [iOS](https://apps.apple.com/us/app/django-files/id6742523003) and [Android](https://github.com/django-files/android-client).
🚀 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](https://github.com/django-files/django-files/issues/new) for any bugs.
- [Overview](#overview)
- [Getting Started](#-getting-started)
- [Docker Quick Start](#-quick-start-with-docker)
- [Docker Compose](#docker-compose)
- [Features](#features)
- [Screen Shots](#screen-shots)
- [Clients](#clients)
- [Apple](#Apple)
- [Android](#Android)
- [Web Browser](#Web-Browser)
- [Usage](#usage)
- [Files](#files)
- [Short URL](#short-urls)
- [User Settings](#user-settings)
- [Site Settings](#site-settings)
- [Variables](#variables)
- [Database](#database)
- [Dev Deploy](#-development-deployment)
- [Frameworks/Credits](#frameworkscredits)
## Overview
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.
## 🚀 Getting Started
> ⚠️ 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](#variables)
### Login Credentials
You **should** override the default credentials with environment variables or settings.env. You will be prompted to set your password on first login.
### 🔧 Quick Start with Docker
Short one-liner to run in foreground:
```bash
docker run --rm -p 80:80 -v ./django-files:/data/media ghcr.io/django-files/django-files:latest
```
Run it in the background:
```bash
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:
```bash
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
```
### Docker Compose:
```yaml
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:
```bash
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](docker-compose-prod.yaml)
## Features
Django Files is packed with features for seamless file management and sharing. More features are in progress!
[Request a Feature](https://github.com/django-files/django-files/discussions/new?category=feature-requests).
### 🔹 Core Features
- Local or S3 storage support
- One-click integration with ShareX, Flameshot
- [iOS Client](https://apps.apple.com/us/app/django-files/id6742523003)
- [Android Client](https://github.com/django-files/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)
### 🔒 Authentication & Security
- Multi-user support with local & OAuth authentication options
- Invite system for user onboarding
- OAuth configuration via Django Admin (no restart required)
### 📊 UI & File Management
- 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
### 📈 Stats & Insights
- Dashboard with user-friendly overview & stats
- Graph-based analytics (work in progress)
- File expiration & view counting
### 📡 Live Streaming
- Live video streaming via HLS (HTTP Live Streaming)
- Real-time live chat with account and anonymous support
- Viewer count/viewer list
- Owner controls: enable/disable chat and anonymous access live
- Push notifications for stream start via Web Push
### External
- Firefox Extension:https://addons.mozilla.org/addon/django-files
- Chrome Extension: https://chrome.google.com/webstore/detail/django-files/abpbiefojfkekhkjnpakpekkpeibnjej
## Screen Shots
Screenshots and UI previews are available on the
[Django Files Github Site.](https://django-files.github.io/screenshots.html) from the menu.
## Clients
Client Applications are available for iOS, Android, and Web Browsers.
### Apple
### Android
[](https://github.com/django-files/android-client/releases/latest/download/app-release.apk)
[](https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://github.com/django-files/android-client)
📲 Click to View QR Codes 📸
[](https://github.com/django-files/android-client/releases/latest/download/app-release.apk)
[](https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://github.com/django-files/android-client)
### Web Browser
[](https://chromewebstore.google.com/detail/django-files/abpbiefojfkekhkjnpakpekkpeibnjej)
[](https://addons.mozilla.org/addon/django-files)
[](https://chromewebstore.google.com/detail/django-files/abpbiefojfkekhkjnpakpekkpeibnjej)
[](https://chromewebstore.google.com/detail/django-files/abpbiefojfkekhkjnpakpekkpeibnjej)
[](https://chromewebstore.google.com/detail/django-files/abpbiefojfkekhkjnpakpekkpeibnjej)
[](https://chromewebstore.google.com/detail/django-files/abpbiefojfkekhkjnpakpekkpeibnjej)
## Usage
Django Files is backwards compatible with
[Zipline](https://zipline.diced.vercel.app/docs/api/upload)
client upload settings.
### Files
Upload Endpoint: `/api/upload/`
Response Type: JSON
```json
{
"files": ["full-url"],
"url": "full-url",
"name": "file-name",
"size": "size-bytes"
}
```
### Short URLs
Upload Endpoint: `/api/shorten/`
Response Type: JSON
```json
{
"url": "full-short-url"
}
```
You can parse the URL with JSON keys `url` or Zipline style `files[0]`
### User Settings
- 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 Settings
- 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)
## Variables
> **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.
| Variable | Description | Example |
| ------------------------------- | --------------------------------- | ---------------------------------------------------- |
| SECRET | App Secret | `JYGTKLztZxVdu5NXuhXGaSkLJosiiQyBhFJ4LAHrJ5YHigQqq7` |
| SITE_URL | Site URL | `https://example.com` |
| USERNAME | Local Username | `admin` |
| PASSWORD | Local Password | `PSZX7TgiSg6aB6sZ` |
| SUPER_USERS | oAuth Sup User IDs | `111150265075298304,111148006983614464` |
| DISCORD_CLIENT_ID | Discord Client ID | `1135676900124135484` |
| DISCORD_CLIENT_SECRET | Discord Secret | `HbSyPWgOBx1U38MqmEEUy75KUe1Pm7dR` |
| GITHUB_CLIENT_ID | GitHub Client ID | `1135676900124135484` |
| GITHUB_CLIENT_SECRET | GitHub Secret | `HbSyPWgOBx1U38MqmEEUy75KUe1Pm7dR` |
| GOOGLE_CLIENT_ID | Google Client ID | `113567690-gvasdfasdf.apps.googleusercontent.com` |
| GOOGLE_CLIENT_SECRET | Google Secret | `GCSDPC-Tskdfix-klsjdf_r32489fj09jfsd` |
| OAUTH_REDIRECT_URL | Discord Redirect | `https://example.com/oauth/callback/` |
| AWS_REGION_NAME | AWS Region Name | `us-east-1` |
| AWS_ACCESS_KEY_ID | AWS IAM User Key | `AKIEAKADFGASDFASGSDAFSDF` |
| AWS_SECRET_ACCESS_KEY | AWS IAM Secret | `eVJsrhftrv2fcwyYcy323Sfhe5svy5436r557` |
| AWS_STORAGE_BUCKET_NAME | Name of s3 bucket | `my-s3-bucket` |
| SIGNED_URL_TTL_SECONDS | Gallery/static signed URL TTL (s) | `14400` |
| SIGNED_DOWNLOAD_URL_TTL_SECONDS | One-shot download signed URL TTL | `900` |
| SIGNED_META_URL_TTL_SECONDS | OG/meta signed URL TTL | `86400` |
| SIGNED_URL_REFRESH_RATIO | Cache TTL fraction of signing TTL | `0.5` |
| AWS_S3_CDN_URL | proxy or cdn url | `https://examples3cdndomain.com` |
| DUO_API_HOST | DUO API Host | `api-abc123.duosecurity.com` |
| DUO_CLIENT_ID | DUO Client ID | `nmoNmuLM72WB3RsNkwuv` |
| DUO_CLIENT_SECRET | DUO Secret | `nmoNmuLM72WB3RsNkwuvnmoNmuLM72WB3RsNkwuv` |
| SENTRY_URL | Sentry URL | `https://a5cb357a@o133337.ingest.sentry.io/1234567` |
| SENTRY_ENVIRONMENT | Sentry ENV | `prod` |
## Database
- 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
| Variable | Description |
| ------------- | ------------------------------------ |
| DATABASE_TYPE | `sqlite3` or `mysql` or `postgresql` |
| DATABASE_NAME | Database name |
| DATABASE_USER | Database username |
| DATABASE_PASS | Database password |
| DATABASE_HOST | Database hostname |
| DATABASE_PORT | Optional if default |
Note: sqlite3 is stored by default in `media_dir/db`
based on what is set in the `docker-compose.yaml` file.
## 🛠 Development Deployment
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.
```text
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)
```text
_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
```
## Frameworks/Credits
- [Python](https://www.python.org/)
- [Django](https://www.djangoproject.com/)
- [Celery](https://docs.celeryproject.org/)
- [Font Awesome](http://fontawesome.io/)
- [Bootstrap](http://getbootstrap.com/)
- [Uppy](https://uppy.io/)
- [Highlight.js](https://highlightjs.org/)
- [Datatables](https://datatables.net/)
- [Swagger](https://swagger.io/)
- [Video.js](https://videojs.com/)
- [Django Channels](https://channels.readthedocs.io/)
[Feature Requests](https://github.com/django-files/django-files/discussions/new?category=feature-requests) |
[Issues](https://github.com/django-files/django-files/issues/new)