# django-filebrowser puts a file manager inside the Django admin

> django-filebrowser extends the Django administration interface with a directory browser that uploads, deletes, edits and renames files, and it links those files to your models through FileBrowseField and to TinyMCE editors. It requires Django 5.x with Grappelli 4.0 and Pillow for the current line, and the 4.0.x branch is still maintained for older Django.

**sehmaschine/django-filebrowser** — Media-Management with Grappelli

- Repository: https://github.com/sehmaschine/django-filebrowser
- Website: http://twitter.com/sehmaschine
- Stars: 998 · Forks: 406
- Language: Python
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/sehmaschine-django-filebrowser

## A file manager that lives in the admin interface

django-filebrowser is an extension to the Django administration interface, and the project describes itself in one line as media management with Grappelli. The point is that the Django admin is already the place where staff create and edit records, and until now it was also the place where you had to hand a URL to a file somewhere else. The extension adds a browser for directories on your server, and with it the ability to upload, delete, edit and rename files.

Three capabilities are listed and they are different in kind. The directory browser is the storage side. The FileBrowseField is the model side, letting you include images or documents in your models and database through that field. The TinyMCE integration is the editor side, letting someone select an image or document while writing rich text.

That last one is the reason this package exists in the form it does. Storing a path in a text field means every editor knows the URL scheme of your media folder and nobody types it correctly. A field that opens a directory listing and returns the reference turns a documentation detail into a click.

The intended user is a Django project with an admin interface and non-technical staff, and the project is maintained by the same author as Grappelli, which is why the two are coupled. The homepage given for the project is a Twitter account, and the full documentation lives on Read the Docs, with translations coordinated through Transifex.

## Grappelli is a hard dependency, not a skin you can skip

The requirement list for FileBrowser 5.0.x is short and non-negotiable: Django 5.x, Grappelli 4.0 and Pillow. The package metadata in setup.py makes the same statement in machine readable form, pinning the admin skin to a narrow range:

```python
    install_requires=[
        "django-grappelli>=4.0,<4.1",
        "pillow",
    ],
```

The upper bound matters more than the lower one. The package is written against the Grappelli 4.0 API, and the constraint stops a resolver from installing a later Grappelli that would break it. If your project already runs Grappelli 4.0, this is a non-issue. If you run a different admin theme, the dependency will pull Grappelli in alongside it, and you have two skins in the same admin rather than one.

Pillow is there for image handling, and the package metadata lists Python 3.10 through 3.14 in its classifiers. The metadata also declares the package as zip_safe=False and calls find_packages with include_package_data=True, so the templates, static files and any data files inside the package are shipped rather than only the Python modules.

The project is packaged with setuptools through setup.py rather than a modern build backend, and the repository carries tox.ini and a runtests.py script, so the test setup is the older style, with a .github workflow running the tests and a .readthedocs.yaml driving the documentation build.

## Two supported branches and a table of releases

The README carries an explicit release table, which is more than most Django admin extensions bother with. FileBrowser 5.0.0 was released on July 27th, 2026 and is compatible with Django 5.0, while FileBrowser 4.0.3 was released on July 27th, 2023 and is compatible with Django 4.0. The dates are three years apart, so the two lines are not in lockstep, and the 4.0 line is not simply an abandoned copy of the 5.0 line.

Two development branches sit underneath those releases. FileBrowser 5.0.1 is the development version for Django 5.x on the branch Stable/5.0.x, and FileBrowser 4.0.4 is the development version for Django 4.0 on Stable/4.0.x. The project states that older versions remain available at GitHub but are not supported any more.

That gives you a clear rule for a project mid-upgrade. If you are on Django 4.0, the 4.0.x branch is the one to track, and it is still receiving work. If you are on Django 5.x, the 5.0.x branch is the current one. Either way you are tracking a branch rather than a tag, which matters for how you pin the dependency in requirements.txt.

The release table is the documentation, though, and the repository publishes no GitHub releases, so there is no package index page listing downloadable artifacts for these versions. The metadata in setup.py still says version="5.0.0" while the README calls 5.0.1 the development version, which is the usual signal that the development version is what the branch carries rather than a published build.

## The licence is described two different ways

Here the sources disagree, and you should read both. The package metadata in setup.py declares license="BSD", and the classifier list includes License :: OSI Approved :: BSD License, with an AUTHORS file naming Patrick Kranzlmueller and Axel Swoboda of vonautomatisch. The licence field on the project listing, however, is marked as Other, a custom licence that GitHub cannot classify, pointing at the LICENSE file in the repository root.

Both statements can be true at once, since a custom LICENSE file can carry BSD terms, but the discrepancy is exactly the kind that makes a licence question worth resolving before you ship. What matters in practice is which text is in the LICENSE file for the version you install, and the repository root is where to read it rather than assuming from a classifier badge.

The other licensing-adjacent point is the plugin ecosystem around it. Grappelli is a separate project by the same author, and the package depends on a specific range of it, which means the two are versioned together in practice even though only one is a hard dependency of the other.

## What the extension does not give you

There is no image processing pipeline described anywhere in the documentation, and Pillow is the only imaging dependency in the metadata. So the file browser gives you storage, browsing and selection, not a derivative generator, a thumbnail service or a CDN upload step. If your media needs resizing, cropping or format conversion on the way in, that is work you add on top.

The browser also inherits the security model of the admin and of your media directory, and the documentation available here does not discuss permissions, per-user folders or how the extension decides which directories are browsable. A file browser by definition exposes a file system through a web interface, so the configuration of that exposure is the part to read carefully in the full documentation rather than assume.

Two smaller limits are worth naming. The extension is tied to a Django admin, so a project with no admin, or an API only service, has no place to put it. And it is tied to Grappelli, as the install requirement shows, so a project that has already invested in a different admin look will either adopt Grappelli as well or skip the package. It is also an older style of package, setuptools with setup.py and no pyproject, runtests.py alongside tox.ini, which matters if your build pipeline assumes modern packaging metadata.

## When a plain upload field is the better answer

The alternative to the whole package is a native Django ImageField or FileField on your model, rendered as an upload widget in the admin. The difference in approach is where the file lives and who controls the reference. A model field stores one file per record, tied to that record, and the admin widget handles the upload for you with no separate browsing step, no separate admin screen and no extra dependency on Grappelli.

django-filebrowser earns its place when the same file is shared between records, when an editor picks from a pool of existing assets rather than uploading something new each time, or when the rich text editor needs to browse. The TinyMCE integration and the standalone directory browser are the parts a model field does not give you, and the FileBrowseField is the part that lets a model reference a file chosen through that browser.

The cost of that capability is the whole extension surface: an admin skin dependency, a browsing UI to learn, and a directory of files that is not versioned by your models. For a site with a handful of images attached to a dozen records, the model field is less machinery. For an intranet where marketing staff publish a shared library of assets and link them everywhere, the browser is the difference between a workable process and a support ticket queue.

## Conclusion

django-filebrowser suits Django projects whose editors need to pick and attach images and documents from the server rather than pasting URLs, and that already use Grappelli 4.0 as their admin theme. It is the wrong choice for a headless API project with no admin, for a team unwilling to take on a second Django skin, or for one that expects a packaged release history. Verify first that the filebrowser folder in your project and the Grappelli version in your requirements match the branch you install, and read the LICENSE file, since the package metadata declares BSD while the project listing marks the licence as a custom one that GitHub cannot classify.

## FAQ

### What does django-filebrowser do in the Django admin?

It adds a browser for directories on your server with the ability to upload, delete, edit and rename files, a FileBrowseField for including images or documents in your models and database, and integration so images and documents can be selected inside TinyMCE.

### Which Django and Grappelli versions does django-filebrowser need?

FileBrowser 5.0.x requires Django 5.x, Grappelli 4.0 and Pillow. The package metadata pins the theme to django-grappelli>=4.0,<4.1 alongside pillow, and the classifiers list Python 3.10 through 3.14.

### Which version of django-filebrowser should I install?

FileBrowser 5.0.0 from July 27th, 2026 targets Django 5.0, and 4.0.3 from July 27th, 2023 targets Django 4.0. The 5.0.x and 4.0.x branches both have development versions, 5.0.1 and 4.0.4, so a project on Django 4.0 can stay on its own branch, and older versions remain at GitHub but are not supported.

### Is django-filebrowser still maintained?

The repository is not archived and the last push was on 2026-08-10, with two development branches for Django 5.x and Django 4.0. It publishes no GitHub releases, so the version list lives in the README and the setup.py metadata rather than on a release page.

### What licence is django-filebrowser released under?

The package metadata declares license="BSD" with a BSD classifier, while the licence field on the project listing is marked as a custom licence that GitHub cannot classify and points at the LICENSE file in the repository root. Read that file for the terms of the version you install.

## Sources

- [Issues](https://github.com/sehmaschine/django-filebrowser/issues)
- [Project website](http://twitter.com/sehmaschine)
- [README](https://github.com/sehmaschine/django-filebrowser/blob/master/README.md)
- [sehmaschine/django-filebrowser on GitHub](https://github.com/sehmaschine/django-filebrowser)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sehmaschine-django-filebrowser