Self-hosted Dify stores uploaded files (documents, images and so on) through OpenDAL. With STORAGE_TYPE=opendal and OPENDAL_SCHEME=fs, files are written to OPENDAL_FS_ROOT inside the API container, which is /app/api/storage by default. A Docker volume mount maps that container path to ./volumes/app/storage on your host.
So if you want your files somewhere else, change only the host (left) side of the volume mount and leave OPENDAL_FS_ROOT alone. The rest of this post explains why, shows the source code behind it, and covers the mistakes that cost me a couple of hours.
Tested with: Dify [editor: add version], self-hosted with Docker Compose on macOS.
Quick answer
| Setting | What it controls | Use this |
|---|---|---|
STORAGE_TYPE | Which storage system Dify uses | opendal (local is deprecated) |
OPENDAL_SCHEME | Which OpenDAL backend | fs for local files |
OPENDAL_FS_ROOT | Where files go inside the container | /app/api/storage |
STORAGE_LOCAL_PATH | The old way of setting the path | Don’t use; migrate to OpenDAL |
| Volume mount, left side | Where files appear on your host | ./volumes/app/storage or any host path |
| Volume mount, right side | The container path being mapped | Must match OPENDAL_FS_ROOT |
Why I wrote this
At the start of 2026 I started building practical AI workflows with tools like Dify, n8n and OpenRouter. One of the first things I hit with self-hosted Dify was file storage.
I couldn’t tell where my files were going, my containers kept restarting with cryptic permission errors, and I had no idea what OPENDAL_FS_ROOT actually did. The docs didn’t make it clear, so I read the code. This is what I learned the hard way.
The three pieces
1. OpenDAL
OpenDAL (Apache Open Data Access Layer) is a storage abstraction library. It gives Dify one consistent API for many backends: the local filesystem, S3-compatible object storage, Azure Blob and more. Dify talks to OpenDAL, and OpenDAL talks to whatever storage you configure.
2. Environment variables (.env)
Your .env file tells Dify which storage backend to use and how to configure it.
3. Docker volume mounts (docker-compose.yaml)
The volume mount connects a folder on your host (your Mac, in my case) to a folder inside the container. Get this wrong and you’ll spend hours scratching your head. I did.
How the pieces fit together
Step 1: The environment variable pattern
When you set OPENDAL_SCHEME=fs, Dify looks for variables that follow this pattern:
OPENDAL_<SCHEME_NAME>_<CONFIG_NAME>So for filesystem storage:
OPENDAL_SCHEME=fstells it to use the local filesystem.OPENDAL_FS_ROOT=<path>tells it where to put files.
Step 2: What happens inside the container
In api/extensions/storage/opendal_storage.py, this function collects the settings:
def _get_opendal_kwargs(*, scheme: str, env_file_path: str = ".env", prefix: str = "OPENDAL_"): kwargs = {} config_prefix = prefix + scheme.upper() + "_" # Creates "OPENDAL_FS_"
# Scans environment variables for key, value in os.environ.items(): if key.startswith(config_prefix): kwargs[key[len(config_prefix):].lower()] = value # OPENDAL_FS_ROOT becomes kwargs['root']Then the OpenDALStorage constructor uses it:
def __init__(self, scheme: str, **kwargs): kwargs = kwargs or _get_opendal_kwargs(scheme=scheme)
if scheme == "fs": root = kwargs.get("root", "storage") # Gets OPENDAL_FS_ROOT value Path(root).mkdir(parents=True, exist_ok=True) # Creates directory inside containerTwo things follow from this:
- Whatever you put in
OPENDAL_FS_ROOTis treated as a path inside the container. Dify will try to create it there. - If you don’t set it, the root falls back to the relative path
storage.
Step 3: The critical connection, volume mounts
In docker-compose.yaml you’ll see:
volumes: - ./volumes/app/storage:/app/api/storage # ^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^ # Your host Inside containerThis was my “aha” moment:
- Left side (
./volumes/app/storage) is a folder on your host, relative to wheredocker-compose.yamllives. - Right side (
/app/api/storage) is a folder inside the container, which has its own separate filesystem. - The mount makes both paths point at the same files. Nothing is copied or synced; it’s one folder seen from two places.
When Dify writes a file to /app/api/storage inside the container, it shows up in ./volumes/app/storage on your host.
Configuration examples
The default setup (works out of the box)
This is what Dify ships with, and it works fine:
STORAGE_TYPE=opendalOPENDAL_SCHEME=fsOPENDAL_FS_ROOT=/app/api/storage # Container path - must match the volume mountvolumes: - ./volumes/app/storage:/app/api/storageResult: files are stored in ./volumes/app/storage/ on your host.
Storing files somewhere else on your host
I wanted all my AI project files in one folder. You only edit the compose file:
# .env (NO CHANGE NEEDED)STORAGE_TYPE=opendalOPENDAL_SCHEME=fsOPENDAL_FS_ROOT=/app/api/storage # Keep this as the container path# docker-compose.yaml (ONLY change the left side)volumes: - ~/Documents/models/dify_data/files:/app/api/storage # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^ # Custom host path Same container pathResult: all Dify files now live in ~/Documents/models/dify_data/files/ on your host.
If more than one service in your compose file mounts /app/api/storage (for example, the worker as well as the API), change the left side for each of them. That way every service sees the same files.
Migrating from the deprecated local storage type
You may still find this in older setups or guides:
# DEPRECATED - old approachSTORAGE_TYPE=localSTORAGE_LOCAL_PATH=storageHere’s why to move off it:
STORAGE_TYPE=localis marked as deprecated in the codebase.STORAGE_LOCAL_PATHis deprecated in favor of OpenDAL’s configuration.
The migration is three lines:
# Before (deprecated)STORAGE_TYPE=localSTORAGE_LOCAL_PATH=storage
# After (current)STORAGE_TYPE=opendalOPENDAL_SCHEME=fsOPENDAL_FS_ROOT=/app/api/storageOpenDAL gives you one configuration pattern for every backend. Switching to object storage later is a matter of changing OPENDAL_SCHEME and setting that backend’s OPENDAL_<SCHEME>_* variables. Check the OpenDAL service docs for the exact names.
Mistakes I made (so you don’t have to)
Mistake #1: Putting a host path (or $HOME) in OPENDAL_FS_ROOT
I thought, “I’ll just point it at my Documents folder”:
# DON'T DO THIS - I learned the hard wayOPENDAL_FS_ROOT=$HOME/Documents/models/dify_data/filesWhat happened:
- My containers started crash-looping.
- The logs showed
PermissionError: [Errno 13] Permission denied: '/Users'. - I spent 2 hours debugging.
Why it failed: the value ended up as my Mac path (/Users/<me>/Documents/...). Remember Step 2: the API process tries to create OPENDAL_FS_ROOT inside the container. There is no /Users directory in the container, and the process isn’t allowed to create one at the filesystem root. So mkdir fails and the container exits.
The fix:
# Always use the container pathOPENDAL_FS_ROOT=/app/api/storageMistake #2: Changing OPENDAL_FS_ROOT to get a custom location
When I wanted a custom storage location, my first instinct was:
# NOPE - this breaks thingsOPENDAL_FS_ROOT=/my/custom/pathThe problem: this path must match the right side of your volume mount. If it doesn’t match, two things can happen:
- Dify fails to create the directory, which is Mistake #1 again.
- Dify writes files into a container folder that isn’t mounted at all. They never appear on your host, and they’re gone when the container is recreated.
The right way:
- Keep
OPENDAL_FS_ROOT=/app/api/storage(the container path). - Change only the left side of the volume mount (the host path).
Mistake #3: Relative paths
A relative path seemed harmless:
# Avoid thisOPENDAL_FS_ROOT=storage # Where even is this?The issue: a relative path resolves against the working directory of the API process inside the container. Is that /app? /app/api? You’d have to go and check.
Better:
# Crystal clear - no ambiguityOPENDAL_FS_ROOT=/app/api/storageDebugging storage problems
Symptom: containers keep restarting
This was my first encounter with Dify: start, crash, start, crash.
First, check the API logs:
docker compose logs --tail=50 api(With the older standalone tool, use docker-compose logs --tail=50 api.)
If you see this, you’ve hit Mistake #1 or #2:
PermissionError: [Errno 13] Permission denied: '/Users'Set OPENDAL_FS_ROOT back to the container path and make sure it matches the right side of the mount.
My debugging checklist
1. Check the OpenDAL variables inside the container:
docker exec docker-api-1 env | grep OPENDAL2. Check the mounted directory inside the container:
docker exec docker-api-1 ls -la /app/api/storage3. Check that the same files show up on the host:
ls -la ./volumes/app/storage/If your container isn’t called docker-api-1, run docker ps to find its name. Alternatively, run the commands through the compose service name, e.g. docker compose exec api env | grep OPENDAL.
The golden rules
OPENDAL_FS_ROOTalways points to a container path: the right side of the volume mount.- Want files elsewhere on your host? Change only the left side of the volume mount.
- Never put
$HOMEor host paths (like/Users/...) inOPENDAL_FS_ROOT. - Use absolute paths.
FAQ
Where does self-hosted Dify store uploaded files?
With the default Docker setup, files go to /app/api/storage inside the API container. That is mounted to ./volumes/app/storage next to your docker-compose.yaml on the host.
How do I change where Dify stores files?
Change the left (host) side of the /app/api/storage volume mount in docker-compose.yaml, for every service that mounts it. Keep OPENDAL_FS_ROOT=/app/api/storage.
Why does Dify crash with Permission denied: '/Users'?
OPENDAL_FS_ROOT is set to a host path, often via $HOME. Dify tries to create that path inside the container and can’t. Set it back to /app/api/storage.
Is STORAGE_TYPE=local still supported?
It’s marked as deprecated in the codebase, along with STORAGE_LOCAL_PATH. Switch to STORAGE_TYPE=opendal with OPENDAL_SCHEME=fs and OPENDAL_FS_ROOT.
Can Dify use object storage instead of the local filesystem?
Yes, OpenDAL supports multiple backends. Set OPENDAL_SCHEME to the backend you want and add that backend’s OPENDAL_<SCHEME>_* variables. The OpenDAL service docs list the options.
Wrapping up
This was one piece of my AI experimentation in 2026. As I keep exploring Dify, n8n and the wider AI tooling world, I’ll keep writing up the quirks I run into. If you have your own Dify storage war stories, I’d love to hear them in the comments.
Happy building! 🚀
Useful links
- Apache OpenDAL Documentation
- OpenDAL Service Configurations
- Dify code:
api/extensions/storage/opendal_storage.py - Agentic Frameworks Compared: LangGraph, CrewAI & More
[keep: comments section]
[keep: “Keep reading” related posts list]