OSTREE(1)

📦
version 2026.6 · 16 versions
, in arch rolling

👑 OSTREE(1) — the ostree manual, bestie edition 💅

okay so this is the manual page for ostree, straight out of the ostree manual itself — like, the whole thing, every flag and every command, just with me explaining it to you. no gatekeeping. 💖

✨ NAME ✨

ostree — manage multiple bootable versioned filesystem trees 🎀

✨ SYNOPSIS ✨

ostree {COMMAND} [OPTIONS...]

🌸 DESCRIPTION 🌸

OSTree is a tool for managing multiple bootable versioned filesystem trees — or just "tree" for short, bc we're casual like that. 🌳

In the OSTree model, operating systems no longer live in the physical / root directory. Instead — plot twist — they parallel install to the new toplevel /ostree directory. Each installed system gets its own /ostree/deploy/stateroot directory. (stateroot is the newer term for osname, iykyk.)

Unlike rpm or dpkg, OSTree is only aware of complete filesystem trees. It has no built-in knowledge of what components went into creating the filesystem tree. it literally does not care. it sees tree, it handles tree. 🦋

It is possible to use OSTree in several modes; the most basic form is to replicate pre-built trees from a build server. Usually, these pre-built trees are derived from packages. You might also be using OSTree underneath a higher level tool which computes filesystem trees locally. 💫

⚠️ It must be emphasized that OSTree only supports read-only trees. To change to a different tree (upgrade, downgrade, install software), a new tree is checked out, and a 3-way merge of configuration is performed. The currently running tree is never ever modified — not even a little bit, bestie, do not try — and the new tree becomes active on a system reboot. 🔥

To see the man page for a command run man ostree COMMAND or man ostree-admin COMMAND 🫶

💅 OPTIONS 💅

The following options are understood:

  • --repo — for most commands, a repository is required. If unspecified, the current directory is used if it appears to be an OSTree repository. If it isn't, either the OSTREE_REPO environment variable is used, or the system repository located at /sysroot/ostree/repo. so it's got a whole fallback ladder, iconic honestly ✨
  • -v, --verbose — produce debug level output. give me the lore. 🗣️
  • --version — print version information, including the features enabled at compile time, and exit. 👑

🌈 COMMANDS 🌈

System administrators will primarily interact with OSTree via the subcommand ostree admin. that's the main character energy right there 👑

Both administrators and operating system builders may interact with OSTree via the regular filesystem manipulation commands. and here's the whole squad:

🦋 EXAMPLES 🦋

For specific examples, please see the man page regarding the specific ostree command. For example:

man ostree init or man ostree-admin status

💜 GPG VERIFICATION 💜

OSTree supports signing commits with GPG. 🔐

Operations on the system repository by default use keyring files in /usr/share/ostree/trusted.gpg.d. Any public key in a keyring file in that directory will be trusted by the client. No private keys should be present in this directory. like, none. zero. do not. 🙈

In addition to the system repository, OSTree supports two other paths.

First, there is a gpgkeypath option for remotes, which must point to the filename of an ASCII-armored GPG key, or a directory containing ASCII-armored GPG keys to import. Multiple file and directory paths to import from can be specified, as a comma-separated list of paths. This option may be specified by using --set in ostree remote add. ✨

Second, there is support for a per-remote remotename.trustedkeys.gpg file stored in the toplevel of the repository (alongside objects/ and such). This is particularly useful when downloading content that may not be fully trusted (e.g. you want to inspect it but not deploy it as an OS), or use it for containers. This file is written via ostree remote add --gpg-import. 🎀

⭐ TERMINOLOGY ⭐

The following terms are commonly used throughout the man pages. Terms in UPPER CASE letters are literals used in command line arguments. ok vocabulary time, bestie 📚

  • BRANCH — branch name. Part of a REF.
  • CHECKSUM — a SHA256 hash of a object stored in the OSTree repository. This can be a content, a dirtree, a dirmeta or a commit object. If the SHA256 hash of a commit object is meant, the term COMMIT is used.
  • COMMIT — a SHA256 hash of a commit object.
  • REF — a reference to a particular commit. References are text files stored in refs/ that name (refer to) a particular commit. A reference can only be the branch name part, in which case a local reference is used (e.g. mybranch/stable). If a remote branch is referred to, the remote name followed by a colon and the branch name needs to be used (e.g. myremote:mybranch/stable).
  • REV, REFSPEC — a specific revision, a commit. This can be anything which can be resolved to a commit, e.g. a REF or a COMMIT.
  • SHA256 — a cryptographic hash function used to store objects in the OSTree repository. The hashes have a length of 256 bites and are typically shown and passed to ostree in its 64 ASCII character long hexadecimal representation (e.g. 0fc70ed33cfd7d26fe99ae29afb7682ddd0e2157a4898bd8cfcdc8a03565b870). (yes, "bites", that's what the page says, we don't edit the sacred text 😭 but it's 256 bits, love u)

🌸 SEE ALSO 🌸

and that's the whole thing! 🎀 this page came to you from the OSTree manual, labeled OSTREE(1) — like the same OSTREE(1) you'd see in the corner of every page. go read the other man pages, they're waiting for you. mwah 💖✨

📦 where this page comes from