YunoHost: a Debian-based server OS that puts app installs behind a single web admin

What YunoHost is, and the problem it removes

YunoHost describes itself as "an operating system aiming to simplify as much as possible the administration of a server". The repository in question is not the whole distribution. It is the core code, written mostly in Python and Bash, and the README points elsewhere for the feature list, the website, and the install documentation. That split matters: if you clone this repository you get the engine, not a bootable image.

The problem it addresses is the gap between renting a machine and running something useful on it. On plain Debian you install a web server, configure TLS, wire up users, then repeat the process for every service you add. YunoHost replaces that sequence with a web admin interface and a catalogue of packaged applications. The audience is people who want to host their own services and are willing to learn one system's conventions instead of five unrelated ones. It is not aimed at engineers who already have configuration management and prefer to keep it.

How the core repository is put together

The top-level layout tells you most of the architecture. src/ holds the Python code, bin/ the entry points, conf/ the configuration templates, locales/ the translations, helpers/ shared shell functions, hooks/ lifecycle scripts, and debian/ the packaging. There is a maintenance/ directory and a tests/ directory alongside them. The presence of debian/ is the strongest structural signal: YunoHost is distributed as a Debian package, not as a container image or a Python wheel you pip install.

Dependencies in pyproject.toml confirm the shape. Moulinette is pulled from its own Git repository on the dev branch, and it is the framework the rest of the code sits on. Bottle provides the HTTP layer. python-debian and packaging handle system package metadata. dnspython, publicsuffix2 and lexicon deal with DNS and certificates. sdbus and zeroconf handle system integration and local discovery. The file itself warns that these dependencies "might not be up to date, please see debian/control instead", which is the honest answer to which list is authoritative for a real install.

Two entries in that dependency list are commented out: dbus-python and python-ldap. Their replacements are present as sdbus and, implicitly, whatever the LDAP path now uses. That is a migration in progress rather than a finished state, and it is the kind of detail the README does not discuss.

Installing YunoHost and running a first command

The README does not contain install steps. It links to the project's install documentation at doc.yunohost.org, and that is where the supported paths live. Because the core is packaged under debian/, the install target is a Debian system, and the recent release tags (13.0.7.1 and 12.1.41.2) suggest two maintained branches.

What the repository does give you is the Python package definition. If you are working on the core rather than deploying it, requires-python is set to >=3.11, and the project declares a tests dependency group. The pyproject.toml file is the only place in the repository that states the Python floor:

[project]
name = "yunohost"
description = "An operating system aiming to simplify as much as possible the administration of a server"
readme = "README.md"
dynamic = ["version"]

requires-python = ">=3.11"

That block is the project's own metadata, so you can read the version constraint directly rather than inferring it. The test configuration sits in the same file under [tool.pytest.ini_options], and the tests group lists pytest and mock among its members:

[tool.pytest.ini_options]
# for --cov-config see https://github.com/nedbat/coveragepy/issues/512
addopts = "-v --cov-confi

The file is truncated at that point in the repository listing, so the full addopts string is not visible here. For an actual server, the documentation is the source of truth for the install command and the supported Debian version. Nothing in this repository states which Debian release the 13.x line targets, so treat that as a question for the install page rather than something you can infer from the code.

Where the abstraction costs you

The catalogue is the product and the constraint at the same time. Applications are packaged by maintainers against YunoHost's conventions, which is why installation is a few clicks. The reverse is that an application outside the catalogue has no easy path. You can install it manually, but you are then maintaining a service that the admin interface does not understand, and upgrades stay your problem.

Version pinning is the second cost. The core depends on pydantic with an upper bound of <2.0 and pyjwt with an upper bound of <2.0. Those constraints are inherited by anything running in the same Python environment. If you need a current pydantic in a service you deploy alongside YunoHost, you have a conflict that the packaging layer will not resolve for you.

The third is that this is a system-wide layer. It manages users, certificates and services on the host. That is what makes it coherent, and it is also why it does not compose neatly with an existing configuration management setup. Running YunoHost on a machine you already manage with Ansible or similar means two systems writing to the same files.

YunoHost against Docker-based self-hosting stacks

The closest comparison is a container-based stack, where each service ships as an image and you compose them yourself. The difference in approach is where the integration lives. In a container stack, the application image is self-contained and the host stays generic; you supply networking, TLS and user management. In YunoHost, the host is the integrated system and the application is packaged to fit it.

That produces opposite failure modes. A container stack breaks when your compose files, volumes or reverse proxy drift out of sync, and the fix is usually local to one service. YunoHost breaks when an app package lags the upstream release, and the fix depends on a maintainer. The container approach also gives you a clean rollback story if you keep images tagged; the README does not document rollback for YunoHost, so that is something to establish before you rely on it.

If your requirement is one service, a container on a minimal host is less machinery. If your requirement is a handful of services with shared users and certificates, YunoHost removes real work.

Maintenance, releases and the AGPL-3.0 licence

The repository is not archived, and the last push was on 2026-09-04. Recent tags include 13.0.7.1 and 13.0.7 on that date, plus 12.1.41.2 on 2026-09-03. Two maintained lines means upgrade paths exist from the older branch, but the repository does not document what upgrading between major versions involves, so that belongs in your pre-adoption checks.

Upgrade cost has a specific shape here. Because the core is a Debian package and applications are packaged separately, kernel and library updates come through normal Debian channels while app updates come through the YunoHost tooling. You are tracking two schedules. The dependency ceilings noted earlier mean the core cannot simply float to the newest Python libraries, so upgrades are deliberate rather than automatic.

The licence is GNU AGPL v3, stated in the README and present as a LICENSE file at the repository root. The practical consequence of AGPL for a self-hoster running the software on their own machine is minimal. The consequence for anyone modifying the core and offering it as a network service is a source-availability obligation. That is a description of the licence's terms, not legal advice; read the licence text if your use is commercial.

What to verify before you commit

Check three things against the install documentation rather than this repository. First, which Debian release your target branch supports, since the packaging directory implies a Debian base but the README does not name a version. Second, whether the applications you actually need are in the catalogue, because everything outside it reverts to manual administration. Third, what the backup and restore path looks like, since the README is silent on both and a self-hosted server without a tested restore is a single point of failure.

If those three check out, the case for YunoHost is straightforward: it is one of the few projects in this space that treats the whole server as the unit of administration rather than a single application. If any of them fails, a plain Debian install with containers gives you the same services with more manual wiring and fewer surprises.

Editorial conclusion

YunoHost suits people who want a working self-hosted server without learning Debian package management, and who accept that the app catalogue defines what is easy. It is the wrong tool if you need a single application on a minimal base, or if you want to run everything as containers. Before committing, check the install documentation for your target Debian release, confirm the app you need is in the catalogue, and decide whether the AGPL-3.0 licence on the core is acceptable for how you intend to use it.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. YunoHost/yunohost on GitHub