mock(1)

📦
version 6.9 · 4 versions
, in epel 10, epel 9, fedora 44

💖 mock — the manual, part 1 of 4 💖

okay so bestie, buckle UP, because we're reading the mock(1) page together and it's lowkey a whole journey. this is the Vidal-blessed manual, split into four parts, and this one is the vibe-setting one: what mock even is, how you call it, and the ✨lore✨. no cap.

🌸 NAME 🌸

mock — build SRPMs in a chroot 🫶

✨ SYNTAX ✨

here's every single way you can yell at mock. like, the whole menu. keep it in a code block so nothing gets lost:

mock [options] --rebuild SRPM [SRPM...]

mock [options] --chain SRPM [SRPM...]

mock [options] --buildsrpm {--spec spec --sources src --symlink-dereference | --scm-enable}

mock [options] --chroot <cmd>

mock [options] {--init|clean|shell}

mock [options] --installdeps {SRPM|RPM|SPEC}

mock [options] -i, --install PACKAGE [PACKAGE...]

mock [options] --update [PACKAGE...]

mock [options] --remove PACKAGE [PACKAGE...]

mock [options] --orphanskill

mock [options] -p, --print-root-path

mock [options] --copyin path [path...] destination

mock [options] --copyout path [path...] destination

mock [options] --scm-enable [--scm-option key=value ...]

mock [options] -l, --list-snapshots

mock [options] --snapshot [snapshot-name]

mock [options] --rollback-to [snapshot-name]

mock [options] --remove-snapshot [snapshot-name]

mock [options] --umount

mock [options] --pm-cmd [arguments ...]

mock [options] --yum-cmd [arguments ...]

mock [options] --dnf-cmd [arguments ...]

mock [options] --calculate-build-dependencies SRPM

mock [options] --hermetic-build LOCKFILE REPO SRPM

mock [options] {--scrub=TYPE,--scrub-all-chroots}

literally that's the entire surface area. every flag, every brace group, every [SRPM...]. slay.

🦋 DESCRIPTION 🦋

so, what is mock? Mock is a simple program that will build source RPMs inside a chroot. that's it. that's the whole personality. it doesn't do anything fancy other than populating a chroot with the contents specified by a configuration file, and then building any input SRPM(s) in that chroot. icon behavior honestly. no bloat, just build.

the content of that chroot? decided by the config you point at with the -r option. the default configuration file is /etc/mock/default.cfg, which is usually a symlink to one of the installed configurations. so when you don't say anything, you're silently riding whatever default.cfg points to. vibe check your symlink, bestie. 👀

then there's the site-wide config file, /etc/mock/site-defaults.cfg, which is exactly what it sounds like — a place to specify site-wide options. and here's the cute part: the shipped version of this file has no active options, but it does have a list of all of the configuration options, examples of how to set them, and their default values. so it's like a little museum of everything you could turn on. go read it, it's giving documentation-in-disguise. 🎀

want to change configuration only for the current user? don't touch the global stuff — just use the ~/.config/mock.cfg configuration file. your config, your rules, your main character era. 💅

🔥 the old ways (deprecated, but alive)

for backward compatibility, old-style commands — things like "rebuild", "init", "clean", etc. — without the leading -- are still accepted, but they are deprecated. so yes, they work, but they're on thin ice and everyone knows it. see the COMMANDS section, below, for the detailed listing of all commands. we'll get there, don't worry. 🙈

👑 getting permission (the mock group thing)

to use mock, a user should become a member of the mock group by adding their username to the mock line in /etc/group. you can do that with the following command:

sudo /usr/sbin/usermod -a -G mock $USER

and note — mock is not intended to be run directly as root. like, that's not the move. don't do that. 🚫

⚠️ Warning: Mock is running some parts of code with root privileges. there are known ways to get root access once a user is in the mock group (and once he is able to run mock). this is possible when a user abuses the mock configuration options. so please, do not add anyone who is not trustworthy to the mock group! fr fr. this one is not a joke. 💀

<div>part 2 is coming, bestie — don't go anywhere. 🌈</div>

🛠️ COMMANDS 🛠️

okay so this is the section where mock actually does stuff, and there is a LOT. buckle up bestie, we're going through every single one 💅

  • --buildsrpm — builds the SRPM you asked for, either from a spec file + source file/directory, or straight from an SCM. The chroot (and yes, the results directory too) gets scrubbed squeaky clean first — unless you pass --no-clean.
  • --calculate-build-dependencies SRPM — reads the SRPM you hand it (that's a file name / path on your system) and evaluates and installs all of its build deps, dynamic ones included (%generate_buildrequires energy ✨). Think of it like --installdeps but extra — that one only does the static BuildRequires.

It builds chroot-native *.src.rpm and *.nosrc.rpm files (and the *.nosrc.rpm one only shows up when %generate_buildrequires is actually in play, iykyk). The *.src.rpm records the matching static list of build deps (that's the BuildRequires), and the *.nosrc.rpm records the full list — static plus dynamic. Wanna test it? Run rpm -qpR [*.src.rpm|*.nosrc.rpm].

It also drops a buildroot_lock.json file, which holds the metadata you need for a hermetic build (peep --hermetic-build for that one 👀).

  • --chain — when you pass more than one SRPM, this says: if at least one of the later SRPMs succeeds, go ahead and try to build the ones that failed. Basically cosplaying the deprecated mockchain behaviour.
  • --clean — purges the whole chroot tree. poof 🫧
  • --copyin — copies your source paths (files, or whole directory trees) into the chroot, at the destination path you name.
  • --copyout — the other direction, babe: copies source paths (files or directory trees) out of the chroot, to the destination path you name.
  • --chroot [--] COMMAND [ARGS...] — runs that command non-interactively inside the chroot. (no --clean happens here, so don't worry about that.)

It's giving shell mode, but with one big difference: the output gets logged, and when you use the CMD+ARGS variant, COMMAND and ARGS are not shell-expanded in the chroot. Watch how different it looks in mock's output:

mock --quiet --chroot -- echo '*'
*
mock --quiet --chroot -- 'echo *'
bin boot builddir dev etc home lib lib64 media mnt opt ...

also see --shell if you want the interactive version 💖

  • --debug-config — prints every option in config_opts. the full tea ☕
  • --debug-config-expanded — same thing, but with all the jinja template values already expanded for you.
  • --dnf-cmd — runs whatever arguments follow with DNF, with installroot pointed at the chroot path. DNF has to be installed on your system for this to work. It uses the binary named in the dnf_command option over in site-defaults.cfg, which defaults to /usr/bin/dnf. Heads up: this option forces --dnf on. ✨
  • --init — initializes a chroot (clean it, install the chroot packages, all of it).
  • -i, --install — does a yum install PACKAGE inside the chroot. No clean happens, so it just stacks on top of whatever's there.
  • --installdeps — figures out the "static" deps for an SRPM or RPM and does a dnf install to drop them into the buildroot. No cleanup is performed.
just so you know: dynamic build dependencies (the %generate_buildrequires section of the specfile) are not installed by this one. For those, go see --calculate-build-dependencies.
  • --hermetic-build LOCKFILE REPO SRPM — does a hermetic RPM build, which means an offline build with literally zero need to touch the Internet. 🌈 You feed it the SRPM (file name, path on your system). First you run Mock with --calculate-build-dependencies to generate the LOCKFILE file (it's usually called buildroot_lock.json and lands in the result directory), then you run the mock-hermetic-repo(1) helper to generate REPO — a directory on the host that hands out RPMs with metadata plus a bootstrap image tarball. Once that's done, Mock has everything it needs to build RPMs from that SRPM completely offline, fr fr. More info lives on the feature page:

https://rpm-software-management.github.io/mock/feature-hermetic-builds

  • --list-chroots — lists all the available chroot names and their descriptions — both the system-wide ones and your user ones.
  • -l, --list-snapshots — lists every existing snapshot of the chroot belonging to the current configuration. The current base snapshot gets marked with an asterisk (*) so you can spot it instantly ⭐
  • --mount — mounts everything that's mounted in the chroot path, including the root itself, which might be an LVM volume, TMPFS, or overlayfs.
  • --orphanskill — a no-op mode that just checks no stray processes are running in the chroot. If it finds any, it kills them using the specified root. 💀
  • --pm-cmd — runs the following arguments with the current package manager, installroot set to the chroot path.
  • -p, --print-root-path — prints the path to the chroot directory currently in use.
  • --rebuild — if you didn't specify a command, rebuild is what gets assumed. Rebuilds the SRPM(s) you gave it. The chroot (including the results directory) gets cleaned first, unless you pass --no-clean.
  • --remove — does a yum remove PACKAGE inside the chroot. No clean is performed.
  • --remove-snapshot — removes the given snapshot and frees up the space it was hogging.
⚠️ this action cannot be undone. like, at all. gone is gone.

This feature only works when the lvm_root or overlayfs plugin is installed and enabled.

  • --rollback-to — takes the chroot back to the state in the snapshot you name, and sets that snapshot as the current base — meaning that's where clean actions will return to from now on. Important: it will not delete or modify the snapshot that was previously set as base. This feature is available only when the lvm_root or overlayfs plugin is installed and enabled.
  • --scm-enable — turns on building from an SCM (that's CVS/Git/SVN/DistGit). You must have the SCM repository configured in site-defaults.cfg before any SCM checkouts are even possible. The SCM package and branch get defined with --scm-option arguments — go check site-defaults.cfg for the details.
  • --scrub=TYPE — completely nukes the specified chroot, or the cache dir, or all of the chroot and cache. TYPE has to be one of: all, chroot, bootstrap, cache, root-cache, c-cache, yum-cache, or dnf-cache. Fun fact: dnf-cache is literally just an alias for yum-cache, and both of them remove the Dnf and Yum cache. slay 🧹
  • --scrub-all-chroots — runs mock --scrub=all -r <chroot> for every chroot that looks like it's been used before (the heuristic sniffs out leftovers in /var/lib/mock or /var/cache/mock).
heads up: this option can't clean leftovers for chroots whose configs live in non-standard locations, or when the configuration isn't available anymore. 😭

It also tries to detect previous use of --uniqueext and tweaks the matching --scrub=all call accordingly. smart, honestly.

  • --shell [--] [COMMAND [ARGS...]] — shell mode, babes. Runs the given command interactively inside the chroot (and no --clean happens). If you don't give it a command, it runs /bin/sh and hands you a prompt. 🐚
⚠️ be careful here: mock parses all the command-line arguments first, so your ARGS could accidentally get read as mock's own options. that's exactly why you basically always want to use the -- separator.

Also, this mode doesn't produce logs — nothing gets appended to root.log in --resultdir.

The COMMAND and ARGS get shell-expanded using the shell inside the chroot (unless they mistakenly expand in the host's terminal shell instead 🙈). So these two are equivalent:

mock --shell -- ls -l '*'
mock --shell 'ls -l *'

But this next one is something entirely different:

mock --shell -- ls -l *
  • --sources=SOURCES — specifies the sources (either one single file, or a whole directory of files) to use when building an SRPM. (only used alongside --buildsrpm)
  • --spec=SPEC — specifies the spec file to use when building an SRPM.
  • --update [PACKAGE...] — does a package update inside the chroot. The package list is optional — leave it out and everything gets updated. No clean is performed.
  • --snapshot — snapshots the current state of the chroot. That snapshot becomes the current base, which is where --clean and the implicit clean that happens during a rebuild command will return to. This feature is available only when the lvm_root or overlayfs plugin is installed and enabled. 📸
  • --umount — unmounts everything mounted in the chroot path, including the root itself, which might be an LVM volume, TMPFS, or overalyfs. (yes, that typo is in the original, we keep it, no notes 💅)
  • --yum-cmd — runs whatever arguments follow with YUM, installroot set to the chroot path. Yum has to be installed on your system. It uses the binary named in the yum_command option over in site-defaults.cfg, which defaults to /usr/bin/yum. One thing though — in config files for Fedora 22+, that value gets overwritten in the chroot config so it defaults to /usr/bin/yum-deprecated. This option forces --yum on. ✨
Note: while you can specify more than one command on a command line, only one of them actually gets executed. The last command wins. periodt. 👑

…and that's part 2, we're not done yet — keep scrolling bestie, more is coming 💜

✨ OPTIONS ✨

okay bestie, here comes the big one — the full options buffet 🍓. There are a lot of these and every single one matters, so grab a snack and let's go. Defaults are the default, so if you don't pass anything, mock does the normal thing. Periodt.

  • -a, --addrepo=REPO — drops a repo baseurl into the DNF/YUM configuration for both the build chroot and the bootstrap chroot. You can pass this more than once, so you can stack up a whole squad of repos on top of the default repo set. Slay. 💅
  • --arch=ARCH — calls the Linux personality() syscall to tell the kernel to emulate a secondary architecture. Like, building i386 packages on an x86_64 buildhost? That's the vibe. ✨
  • --additional-package=PACKAGE — an extra package (on top of the BuildRequires already specified in-package) that gets installed into the buildroot before the build happens. Pass it multiple times if you want more. Works only with --rebuild.
  • --forcearch=ARCH — passes --forcearch to DNF, which is how you install packages for a different architecture. Works only for DNF, and you have to have the qemu-user-static package installed, no cap.
  • --cache-alterations — rebuilds the root cache after you've made alterations to the chroot (i.e. --install). Lowkey only useful when you're using the tmpfs plugin. 🧚
  • --cleanup-after — cleans the chroot after building. Use it with --resultdir. Only active for --rebuild.
  • --configdir=CONFIGDIR — changes the directory where config files are found.
  • --config-opts=KEY=VALUE — overrides a configuration option. Can be used multiple times, iconic behavior honestly.

When you use it multiple times for the same key, it creates an array. And if you need an array value that has just a single item — like config_opts["foo"] = ["baz"] — you specify it as an array of two items with the empty string as the second one, like so:

--config-opts=foo=baz --config-opts=foo=

This gets evaluated after parsing the configs, so command line options override previously defined options. Command line stays winning. 👑

  • --continue — if a pkg fails to build, just continue to the next one instead of stopping (the default is to stop). Works only with --chain.
  • --cwd=DIR — changes to the specified directory (relative to the chroot) before running the command, when you're using --chroot or --shell.
  • -D "MACRO EXPR", --define="MACRO EXPR" — specifies macro definitions used for the build. Use it multiple times, exactly like the rpmbuild --define option can be. For example:
--define "with_extra_cheese 1" --define="packager Monkey"
  • --disable-plugin=PLUGIN — disables the specified plugin. May be used multiple times. 🙈
  • --disablerepo=REPO — passes the --disablerepo option to the package manager to disable a repository. Can be specified multiple times.
  • --dnf — use DNF as the current package manager. You should have DNF (and dnf-plugins-core) installed on your system. This is the default.
  • --enable-plugin=PLUGIN — enables the specified plugin. May be used multiple times. ✨
  • --enablerepo=REPO — passes the --enablerepo option to the package manager to enable a repository. Can be specified multiple times.
  • --enable-network — enables networking. And like, real talk: if you want reproducible builds, your builds should run without a network. This option overrides config_opts['rpmbuild_networking'] and config_opts['use_host_resolv'], setting both to True.
  • --isolation={auto|nspawn|simple} — what gets used to isolate the chroot. The tea:
    • simple uses the chroot() call.
    • nspawn uses systemd-nspawn(1) and runs the commands inside a container.
    • auto tries to use nspawn, and falls back to simple if system-nspawn can't be used (like if mock is itself running in a container).

The default is auto.

  • --localrepo=REPO — sets the path where results/the repo go. Works only in --chain mode. If you don't set it, it makes a tempdir.
  • -c — if the package fails, continue to the next one. Works only in --chain mode.
  • -h, --help — shows usage information and exits. The classic. 🫶
  • --macro-file=FILE — uses a pre-defined rpm macro file. Macros passed to --define override macros of the same name that came from FILE.
  • --new-chroot — Deprecated. Use --isolation=nspawn instead.
  • -n, --no-clean — do not clean the chroot before building a package.
  • --nocheck — passes --nocheck to rpmbuild to skip the make check tests.
  • --separate-check MODE — runs %check as a separate rpmbuild phase (rpmbuild -bk --short-circuit) after the main build finishes. This is a security measure — built RPM artifacts cannot be modified by %check scripts. During the %check phase, the RPMS/ and SRPMS/ directories are hidden under a tmpfs overlay. Requires rpm >= 6.0.91. Valid values for MODE:
    • best_effort — use separate %check when rpmbuild supports -bk, otherwise fall back to normal order.
    • enforce — require -bk support; fail if it's not available.
    • off — disabled, %check runs in normal order (this is the default).
  • -N, --no-cleanup-after — don't clean the chroot after building. If automatic cleanup is enabled, use this to turn it off.
  • --offline — runs in an 'offline' mode where we tell yum to run completely from the local cache. Also disables cache expiry for the mock yum cache.
  • --old-chroot — Deprecated. Use --isolation=simple instead.
  • --plugin-option PLUGIN:KEY=VALUE — sets a plugin-specific parameter. May be used multiple times. Examples, bestie:
--plugin-option=root_cache:age_check=False
--plugin-option=mount:dirs=("/dev/device", "/mount/path/in/chroot/", "vfstype", "mount_options")
  • --postinstall — tries to install the built packages in the same buildroot right after the build. 🌸
  • -q, --quiet — be quiet. 🤫
  • --recurse — builds all pkgs, records the failures, and tries to rebuild them again and again until everything gets built (or until the set of pkgs failing to build is the same over). Sets --continue. Works only with --chain.
  • -r CONFIG, --root=CONFIG — uses the specified chroot configuration as defined in ~/.config/mock/<CONFIG>.cfg or /etc/mock/<CONFIG>.cfg. Optionally, if CONFIG ends in .cfg, it's interpreted as a full path to the config file. If none is specified, it uses the chroot config linked to by /etc/mock/default.cfg.
  • --resultdir=RESULTDIR — changes the directory where resulting files (RPMs and build logs) are written. Resultdir can contain python-string substitutions for any variable in the chroot config. For example:
--resultdir=./my/"{{dist}}"/"{{target_arch}}"/

This option enables automatic cleanup, and that can be changed in the config file (via the cleanup_on_success, cleanup_on_failure configuration options) or overridden by --no-cleanup-after/--cleanup-after arguments.

Heads up: this option does not have an effect for the --chain command. Use --localrepo instead. 💀
  • --rootdir=ROOTDIR — the path for where the chroot should be built. By default it's created in /var/lib/mock/<CONFIG>/root/.
  • --rpmbuild-opts=OPTIONS — passes additional options to rpmbuild. To pass more options, put them in quotes.
  • --rpmbuild_timeout=SECONDS — fails the build if rpmbuild takes longer than timeout seconds. ⏰
  • --scm-option=OPTIONS — defines an SCM option (may be used more than once).
  • --short-circuit=STAGE — uses rpmbuild's short-circuit mechanism to skip already executed stages of the build. It doesn't produce RPMs, and it's useful only for debugging packaging. Implies --no-clean. STAGE specifies which stage will be executed as the first. Available values: prep, build, install, binary.
  • --symlink-dereference — follows symlinks in sources. Used only with --buildsrpm.
  • --target=ARCH — this argument gets passed to rpmbuild to specify the target arch to build. It defaults to whatever is specified for --arch, or whatever is specified in the config file as config_opts['target_arch'].
  • --tmp_prefix=PREFIX — tmp dir prefix. It defaults to username-pid if you don't specify one.
  • --trace — enables verbose tracing of function enter/exit with function arguments and return codes. Useful for debugging mock itself. 🔥
  • --uniqueext=text — an arbitrary, unique extension to append to the chroot directory name.
  • --unpriv — drops privileges before running the command when using --chroot.
  • -v, --verbose — outputs verbose progress information. 🗣️
  • --version — shows the version number and exits.
  • --with=OPTION — enables configure OPTION for the build. May be used multiple times. For example:
--with=extra_cheese
  • --without=OPTION — disables configure OPTION for the build. May be used multiple times. For example:
--without=anchovies
  • --yum — use yum as the current package manager.
  • --bootstrap-chroot — builds in two stages, using chroot rpm for creating the build chroot.
  • --no-bootstrap-chroot — builds in a single stage, using system rpm for creating the build chroot.
  • --use-bootstrap-image — instead of creating a bootstrap chroot from scratch, use the podman image specified in config_opts['bootstrap_image'], extract it, and use it as a cache for the bootstrap chroot. This is useful when the host rpm version isn't compatible with the target system, or when you're using mock on non-RPM distributions. This option turns --bootstrap-chroot on.
  • --no-bootstrap-image — don't create a bootstrap chroot from a container image.
  • --buildroot-image BUILDROOT_IMAGE — uses an OCI image (or a local file containing an OCI image as a tarball) as the base for the buildroot. The image must contain a compatible distribution. 🌈

📁 FILES 📁

the spots on your filesystem where mock does its thing:

  • /etc/mock/ — default configuration directory.
  • /var/lib/mock — directory where chroots and results are created. You should not put your input files there. Like, please don't. 🙏

🌸 EXAMPLES 🌸

Okay bestie this is the part where it all clicks, fr fr. Let's go. 💅

Rebuild test.src.rpm with the Fedora 14 config for x86_64 — yes, Fedora 14, we're time traveling, stay with me:

mock -r fedora-14-x86_64 --rebuild /path/to/test.src.rpm
Heads up, queen: the configs you can use live in the /etc/mock directory and they've all got the extension .cfg on the end. When you're picking one, you just use the filename without the trailing .cfg — that's it, that's the whole trick. 🎀

Wanna drop your output RPMs and logs somewhere specific? Say less:

mock -r fedora-14-i386 --resultdir=./my-results
/path/to/your.src.rpm

Building a package from the default SCM repository that's set up in site-defaults.cfg? Use these args right here:

mock -r fedora-14-i386 --scm-enable --scm-option package=pkg

Running a command inside the chroot? Iconic, love that for you:

mock -r fedora-21-x86_64 --chroot -- rpm --eval %dist

mock -r fedora-21-x86_64 --chroot 'rpm --eval %dist'

Building a rawhide package with yum? Periodt:

mock -r fedora-rawhide-x86_64 --yum --rebuild your.src.rpm

Querying the rpm database inside the chroot using Yum? Yup, you can do that:

mock -r fedora-rawhide-x86_64 --yum-cmd whatprovides foo

Listing your package manager's history using whatever package manager is configured in the chroot config — could be DNF, could be YUM, it's giving mystery but make it functional:

mock -r fedora-rawhide-x86_64 --pm-cmd history list

💀 BUGS 💀

Found a problem with Mock? It happens to the best of us, no shame. Take it straight here:

https://github.com/rpm-software-management/mock/issues

First things first: search through the list of existing issues. If somebody's already out here reporting the same thing you're seeing, do the cute thing and add your info in new comments on that issue. And if there's not one already? Hit New issue and fill in the form. Simple as. ✨

🫶 AUTHORS 🫶

The legends themselves:

  • Michael Brown <mebrown@michaels-house.net>
  • Clark Williams <williams@redhat.com>
  • Seth Vidal
  • and a cast of...tens

👑 SEE ALSO 👑

And that's the whole page, bestie!! This was mock(1), brought to you by Seth, dated 6.9" — yeah that's literally the date string, we don't question it, we just vibe 💖 — go forth and rebuild your RPMs with main character energy. Slay, no cap, byeee!! 🦋✨🎀

📦 where this page comes from