Media Files Folder

Other languages:

Joomla!

≥ 5.3

Introduction[edit]

Starting with Joomla 5.3, a new root-level folder named "files" is available in the Media Manager. This enhancement allows better separation between traditional media files (such as images) and other types of documents (such as PDFs, Word files, etc.). The "files" folder is also supported by the default Local FileSystem adapter.

Why this change?[edit]

Previously, all uploaded media were stored inside a single directory (usually "images"), which could make organization difficult when handling non-image documents. The new "files" folder is designed to help keep files structured and easier to manage, especially when used for attachments, downloadable content, or custom fields.

How it works[edit]

In the Media Manager:

A new root folder named "files" is now visible alongside "images"

You can upload files into it, create subfolders, and use them in articles, fields, or third-party extensions

Behavior of Custom Fields[edit]

Custom fields of type "media" or "file" now use the "files" folder as their default storage location, unless another path is manually set in the field configuration.

After updating from an older version[edit]

If you update an existing Joomla site to version 5.3, the "files" folder will be created automatically, but will be empty by default.

To start using it, follow these steps:

In the Media component, set the Path to Files Folder option to files
Go to System → Plugins → FileSystem - Local and add files to the list of allowed directories (by default, only images is listed)

This enables Joomla to handle uploads to the "files" folder correctly.

What is the Local FileSystem Adapter?[edit]

Joomla uses a system of "adapters" to define how and where files are stored. By default, Joomla uses the Local FileSystem adapter, which simply stores files on the same server where your site is hosted.

Other adapters (such as Amazon S3 or Dropbox) may be configured, but the local adapter is used by most installations.

The new "files" folder is fully supported by this local storage system.

Allowing additional file types[edit]

Example of allowed extensions and MIME types configuration

For security reasons, Joomla only allows uploading certain file types by default. If you want to upload files like .zip or .docx, you must allow their MIME types in Joomla's media settings.

How to configure[edit]

To allow a specific file type to be uploaded, you must configure both:

its file extension (e.g. docx)

its MIME type (e.g. application/vnd.openxmlformats-officedocument.wordprocessingml.document)

Go to System → Global Configuration → Media

Locate the Legal MIME Types field

Add the required types. For example:

For .zip: application/zip

For .docx: application/vnd.openxmlformats-officedocument.wordprocessingml.document

Also make sure the file extension is listed in the Legal Document Extensions (File Types).

Use cases[edit]

Uploading downloadable documents for users (PDF, DOCX, etc.)

Managing file attachments in custom fields or third-party extensions

Keeping documents separated from visual media assets

Feature origin[edit]

This improvement was introduced in Joomla 5.3 via Pull Request #43532.

J5.x