Mealie for self-hosted recipe management: Docker install, URL imports and where it stops

What Mealie solves, and for whom

The README describes Mealie as a self hosted recipe manager, meal planner and shopping list. The problem it addresses is scattered recipes: browser bookmarks, screenshots, and links that rot. Mealie stores recipes in a database you control, and the README states you can add one by providing the URL, after which Mealie imports the relevant data, or by entering a family recipe in the UI editor. The stated audience is the household, not a single power user. The key features list includes a Meal Planner for the coming week, a Shopping List organised into sections of your local supermarket, and Cookbooks that group recipes by your own criteria. It also exposes an API for third party applications, which is what makes integrations possible at all. If you only want to save recipe links for yourself and never plan meals or build a shopping list, the meal planner and list features are dead weight, and a plain bookmark manager or note app would do the same job with less to maintain. Mealie earns its keep when more than one person cooks from the same collection.

How the backend, frontend and import pipeline fit together

The repository layout shows a Python package in mealie/ and a separate frontend/ directory, plus a docs/ folder that builds the documentation site. The pyproject.toml declares FastAPI, SQLAlchemy, alembic and uvicorn, so the backend is an ASGI application with an ORM layer and database migrations. The frontend is Vue, per the README, and talks to the same REST API that third party applications use. Recipe import is not a single library call: the dependency list includes recipe-scrapers, extruct, beautifulsoup4, lxml and httpx, which is the shape of a pipeline that fetches a page, extracts structured data where a site provides it, and falls back to parsing HTML. Ingredient handling pulls in ingredient-parser-nlp and pint, so quantities and units are parsed and converted rather than stored as raw strings. There is also yt-dlp in the dependency list, which suggests import sources beyond ordinary web pages, though the README does not document video import. Persistence is SQLAlchemy with alembic migrations, and pyproject.toml lists psycopg2-binary under an optional pgsql extra, so Postgres is supported alongside whatever default the deployment uses. The API surface is the integration point; the Vue app is one client of it.

Installing Mealie with Docker and importing your first recipe

The README points to Docker as the deployment route and links the GitHub Container Registry package page for the image. It also links the documentation at docs.mealie.io. The README does not print a compose file or any run command, so there is nothing to copy here verbatim; the image tag, the port mapping, the volume path and the database configuration all have to come from the documentation site before you deploy. What the README does establish is the shape of the deployment: a Mealie container pulled from the registry, plus persistent storage so recipes survive a container replacement. The pyproject.toml adds one concrete detail, the optional pgsql extra that pulls in psycopg2-binary, so Postgres is a supported database rather than an afterthought.

Once the service is reachable, the first account you create becomes the administrator, which is why you should not expose it to the internet before that step. From the UI, use the recipe import flow and paste a URL. The README says Mealie will automatically import the relevant data. What you should see is a new recipe entry with a title, ingredients and instructions; what you should not assume is that every site imports cleanly, because extraction depends on the markup the site serves. If a page fails, the UI editor is the documented fallback for entering the recipe by hand.

Once recipes exist, the Meal Planner and Shopping List are the features that justify the setup. The API is available for anything the UI does not cover.

Where Mealie breaks down or is the wrong choice

URL import is the headline feature and the most fragile one. It depends on recipe-scrapers, extruct and HTML parsing against sites that Mealie does not control. When a site changes its markup or serves content behind a paywall or JavaScript gate, extraction degrades. The README does not document import failure handling or a retry mechanism, so plan on manual correction through the editor. The second limitation is mobile. The related searches show people looking for a Mealie Android app, and the README does not describe an official Android or iOS client. The Vue frontend is a web application; on a phone you are using a browser against your own server, which means you need remote access working before the app is pleasant to use. The README does not document a remote access setup. Third, this is a service you now operate. A container, a database, a volume, and upgrades that run alembic migrations. If nobody in the household will maintain that, a hosted recipe service is the honest answer. Fourth, the AGPL-3.0 licence is a real consideration if you intend to modify Mealie and expose it to users over a network.

Mealie compared with Tandoor Recipes

Tandoor Recipes is the comparison people search for, and the difference is architectural rather than cosmetic. Both are self-hosted recipe managers with meal planning and shopping lists, and both are Python projects. Tandoor is built around Django, which brings its own admin interface and a mature ecosystem of Django packages; Mealie is built on FastAPI with SQLAlchemy and alembic, which is a lighter ASGI stack and a smaller framework surface. In practice that shapes extensibility. If you want to write a Django app that shares models and authentication with your recipe manager, Tandoor's foundation is the easier one to extend. If you want a documented REST API to call from a script, a Home Assistant automation, or another service, Mealie's API-first framing is the stated design. The frontends differ too: Mealie's is Vue, and Tandoor's is Django templates plus its own frontend work. Neither project is a hosted service, so the operational burden is similar. The honest way to choose is to stand up both against your own recipe sources and see which one imports the sites you actually use, because that is where they will diverge most for you.

Upgrades, maintenance cost and the AGPL-3.0 licence

The last push to the default branch mealie-next was on 2026-08-24, and the most recent release listed is v3.24.0 on the same date, following v3.23.1 and v3.23.0 on 2026-08-18. That is a project with frequent releases, which cuts both ways: fixes arrive quickly, and so do migrations. Because alembic is a declared dependency, schema changes are applied when the application starts or when a migration step runs. The practical cost is that you should back up the database and the data volume before pulling a new image, and you should read the release notes for the version you are moving to. The README does not document rollback, so downgrading after a migration is not something you can count on. Budget for reading release notes on each upgrade rather than tracking a long-term support branch, because the README does not describe one. On licensing, Mealie is distributed under the AGPL-3.0 licence per the README, and pyproject.toml records AGPL-3.0-only. Running it for your household is normal use. The obligation that matters is the network clause: if you modify Mealie and let users interact with it over a network, the AGPL requires offering those users the corresponding source. That is a reason some companies keep it out of internal products. This is a description of the licence, not legal advice; check with counsel if you plan to build on it.

What the documentation does not answer

Several things a new operator needs are simply absent from the README. There is no compose file, no environment variable reference, and no statement of which database the default deployment uses. The homepage is docs.mealie.io and the README points there, so the answers live in the docs, not in the repository root. There is also no documented remote access story, despite the volume of searches about accessing Mealie from outside the home network. There is no documented rollback procedure, and no statement about how a failed URL import is surfaced to the user. The README does mention a demo at demo.mealie.io, which is the cheapest way to see the UI before you commit to running anything. If you are evaluating Mealie for a household, look at the demo, then read the docs sections on installation and backups, then decide. The repository is not archived, and the release cadence is visible in the release list, but none of that tells you whether the specific sites you cook from will import cleanly.

Editorial conclusion

Adopt Mealie if you want a household recipe database on your own hardware and you are willing to run a container plus a database. Do not adopt it if you need a native Android or iOS app from the project, or if AGPL-3.0 obligations around network use are a problem for your organisation. Before committing, verify the current container image tag on the GitHub Container Registry, confirm whether you will run SQLite or Postgres, and test one URL import against a site you actually cook from, because the README does not document rollback or import failure handling.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes