Customize your environment file
.env (environment) file contains variables you can change to customize your pod. You can change these variables at any time to alter how your pod runs.
You need to restart your Funkwhale services after changing your
sudo systemctl restart funkwhale.target
sudo docker compose restart
Some environment variables accept a URL as a value. To encode URLs and avoid problems with special characters, use
urllib.parse on your URL value.
python3 -c 'import urllib.parse; print(urllib.parse.quote_plus("p@ssword"))
- FUNKWHALE_HOSTNAME = mypod.audio
Hostname of your Funkwhale pod, e.g.
- FUNKWHALE_PROTOCOL = https
Protocol end users will use to access your pod, either
Database and redis configuration
- DATABASE_URL = postgresql://<user>:<password>@<host>:<port>/<database>
The URL used to connect to the PostgreSQL database. Defaults to an auto generated url build using the DATABASE_HOST, DATABASE_PORT, DATABASE_USER, DATABASE_PASSWORD and DATABASE_NAME variables.
- DB_CONN_MAX_AGE = 300
The maximum time in seconds before database connections close.
- CACHE_URL = redis://<host>:<port>/<database>
The URL of your redis server. For example:
If you’re using password auth (the extra slash is important) -
redis:///run/redis/redis.sock?db=0over unix sockets
If you want to use Redis over unix sockets, you also need to update
Accounts and registration
- ACCOUNT_EMAIL_VERIFICATION_ENFORCE = true
Set whether users need to verify their email address before using your pod. Enabling this setting is useful for reducing spam and bot accounts. To use this setting you need to configure a mail server to send verification emails. See
Superusers created through the command line never need to verify their email address.
- USERS_INVITATION_EXPIRATION_DAYS = 7
The number of days before a user invite expires.
- DISABLE_PASSWORD_VALIDATORS = true
Whether to disable password validation rules during registration. Validators include password length, common words, similarity with username.
- ACCOUNT_USERNAME_BLACKLIST = test,funkwhale
List of usernames that can’t be used for registration. Given as a list of strings.
- LDAP_ENABLED = False
Whether to enable LDAP authentication.
See Configure LDAP for more information.
Media storage and serving configuration
- MEDIA_URL = https://mypod.audio/media/
The URL from which your pod serves media files. Change this if you’re hosting media files on a separate domain, or if you host Funkwhale on a non-standard port.
- MEDIA_ROOT = /srv/funkwhale/data/media
The path where you store media files (such as album covers or audio tracks) on your system. Make sure this directory actually exists.
- PROXY_MEDIA = true
Whether to proxy audio files through your reverse proxy. We recommend you leave this enabled to enforce access control.
If you’re using S3 storage with
AWS_QUERYSTRING_AUTHenabled, it’s safe to disable this setting.
- EXTERNAL_MEDIA_PROXY_ENABLED = false
Whether to proxy attachment files hosted on third party pods and and servers. We recommend you leave this set to
true. This reduces the risk of leaking user browsing information and reduces the bandwidth used on remote pods.
- ATTACHMENTS_UNATTACHED_PRUNE_DELAY = true
The delay in seconds before Funkwhale prunes uploaded but detached attachments from the system.
- REVERSE_PROXY_TYPE = nginx
Set your reverse proxy type. This changes the headers the API uses to serve audio files. Allowed values:
- PROTECT_FILES_PATH = /_protected
The path used to process internal redirection to the reverse proxy.
Don’t insert a slash at the end of this path.
- NGINX_MAX_BODY_SIZE = 100M
Controls the maximum size of file that users can upload.
You can control how much total storage a user can access with the Upload Quota setting.
S3 storage configuration
- AWS_QUERYSTRING_AUTH = False
Whether to include signatures in S3 URLs. Signatures are used to enforce access control.
Defaults to the opposite of
- AWS_QUERYSTRING_EXPIRE = 3600
The time in seconds before AWS signatures expire. Only takes effect you enable
- AWS_ACCESS_KEY_ID = 'my_access_key'
Access-key ID for your S3 storage.
- AWS_SECRET_ACCESS_KEY = 'my_secret_key'
Secret access key for your S3 storage.
- AWS_STORAGE_BUCKET_NAME = 'my_bucket'
Your S3 bucket name.
- AWS_S3_CUSTOM_DOMAIN = None
Custom domain to use for your S3 storage.
- AWS_S3_ENDPOINT_URL = https://minio.mydomain.com
If you use a S3-compatible storage such as minio, set the following variable to the full URL to the storage server.
- AWS_S3_REGION_NAME = eu-west-2
If you’re using Amazon S3 to serve media without a proxy, you need to specify your region name to access files.
- AWS_LOCATION = funkwhale_music
A directory in your S3 bucket where you store files. Use this if you plan to share the bucket between services.
In-place import configuration
- MUSIC_DIRECTORY_PATH = /srv/funkwhale/data/music
The path on your server where Funkwhale places files from in-place imports. This path needs to be readable by the webserver and
Don’t insert a slash at the end of this path.
On Docker installations, we recommend you use the default
/musicpath. On Debian installations you can use any absolute path. Defaults to
You need to add this path to your reverse proxy configuration. Add the directory to your
- MUSIC_DIRECTORY_SERVE_PATH = /srv/funkwhale/data/music
On Docker setups the value of
MUSIC_DIRECTORY_PATHmay be different from the actual path on your server. You can specify this path in your
volumes: - /srv/funkwhale/data/music:/music:ro
In this case, you need to set
/srv/funkwhale/data/music. The webserver needs to be able to read this directory.
Don’t insert a slash at the end of this path.
- THROTTLING_ENABLED = True
Whether to enable throttling (also known as rate-limiting). We recommend you leave this enabled to improve the quality of the service, especially on public pods .
- THROTTLING_RATES = signup=5/d,password-reset=2/d,anonymous-reports=5/d
Throttling rates for specific endpoints and app features. Tweak this if you’re hitting rate limit issues or if you want to reduce the consumption of specific endpoints. Takes the format
See Rate limit API endpoints for a list of available endpoints and their default limits.
- ADMIN_URL = '^api/admin/'
Path to the Django admin dashboard.
- EXTERNAL_REQUESTS_VERIFY_SSL = True
Whether to enforce TLS certificate verification when performing outgoing HTTP requests.
We recommend you leave this setting enabled.
- EXTERNAL_REQUESTS_TIMEOUT = 10
Default timeout for external requests.
- FEDERATION_OBJECT_FETCH_DELAY = 4320
The delay in minutes before a remote object is automatically refetched when accessed in the UI.
- FEDERATION_DUPLICATE_FETCH_DELAY = 3000
The delay in seconds between two manual fetches of the same remote object.
- TAGS_MAX_BY_OBJ = 30
Maximum number of tags that can be associated with an object. Extra tags are ignored.
- MUSICBRAINZ_HOSTNAME = 'musicbrainz.org'
The hostname of your MusicBrainz instance. Change this setting if you run your own server or use a mirror. You can include a port number in the hostname.
- MUSICBRAINZ_CACHE_DURATION = 300
Length of time in seconds to cache MusicBrainz results.
Channels and podcast configuration
- PODCASTS_RSS_FEED_REFRESH_DELAY = 86400
The delay in seconds between two fetch of RSS feeds.
A lower rate means new episodes are fetched sooner, but requires more resources.
- PODCASTS_RSS_FEED_MAX_ITEMS = 250
Maximum number of RSS items to load in each podcast feed.
- PODCASTS_THIRD_PARTY_VISIBILITY = 'me'
By default, only people who subscribe to a podcast RSS have access to its episodes. Change to
everyoneto change the default visibility.
Changing this value only affect new podcasts.
- SUBSONIC_DEFAULT_TRANSCODING_FORMAT = 'mp3'
The default format files are transcoded into when using the Subsonic API.
- EMAIL_CONFIG = consolemail://
SMTP configuration for sending emails. Possible values:
EMAIL_CONFIG=consolemail://: output emails to console (the default)
EMAIL_CONFIG=dummymail://: disable email sending completely
On a production instance, you’ll usually want to use an external SMTP server:
- DEFAULT_FROM_EMAIL = Funkwhale <noreply@yourdomain>
The name and email address used to send system emails. Defaults to
Name <email address>
- EMAIL_SUBJECT_PREFIX = '[Funkwhale] '
Subject prefix for system emails.
- FUNKWHALE_PLUGINS_PATH = '/srv/funkwhale/plugins/'
Path to a directory containing Funkwhale plugins. These are imported at runtime.
- FUNKWHALE_PLUGINS = ['funkwhale_api.contrib.scrobbler', 'funkwhale_api.contrib.listenbrainz', 'funkwhale_api.contrib.maloja']
List of Funkwhale plugins to load.
- INSTANCE_SUPPORT_MESSAGE_DELAY = 15
The number of days before your pod shows the “support your pod” message. The timer starts after the user signs up.
- FUNKWHALE_SUPPORT_MESSAGE_DELAY = 15
The number of days before your pod shows the “support Funkwhale” message. The timer starts after the user signs up.
- MIN_DELAY_BETWEEN_DOWNLOADS_COUNT = 21600
The required number of seconds between downloads of a track by the same IP or user to be counted separately in listen statistics.
- MARKDOWN_EXTENSIONS = ['nl2br', 'extra']
A list of markdown extensions to enable.
- LINKIFIER_SUPPORTED_TLDS = ['audio']
Additional TLDs to support with our markdown linkifier.
- LOGLEVEL = info
str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.