Skip to main content
bake and bakefile load exactly one bakefile.py per run. They never merge several files, and a command missing from the chosen file is an error, not a lookup in another file.

Resolution order

  1. With -g, the Global bakefile.py.
  2. With -C <dir>, only <dir>. No walk-up and no fallback, so a typo in the path fails instead of loading another file.
  3. Otherwise, the nearest bakefile.py found by walking up from the current directory to the filesystem root.
  4. If walk-up finds nothing, the Global bakefile.py, if you have created one.
-f changes only the file name, and every step looks for that name. bake -f tools.py build walks up looking for tools.py, then falls back to the global tools.py. -f still takes a name, never a path (see file name errors).
With nested projects, the nearest bakefile.py wins: from monorepo/services/api/, a services/api/bakefile.py is used over monorepo/bakefile.py. Walk-up crosses repository boundaries, so a git submodule without its own bakefile.py uses the outer repo’s. bake --help shows which file was loaded, marked (global) when it is the Global bakefile.py:
When a file is found, bakefile subcommands other than init print the same Using: <path> line to stderr before running, since walk-up may have picked a parent’s file. -vvv logs which step matched. When nothing is found, the error lists what was searched and where a Global bakefile.py would go:

Commands run in the bakefile.py’s directory

Commands always run in the chosen bakefile.py’s directory, wherever you call bake from. Relative paths in your commands (self.ctx.run("pytest tests"), Path("dist")) behave the same from a subfolder as from the root. For the Global bakefile.py, that is the global directory, resolved through symlinks.

Global bakefile.py

A Global bakefile.py holds commands that belong to no project, such as syncing dotfiles or personal utilities. It is opt-in: nothing exists until you create it, and without one, plain bake behaves as before (only the not-found message is new).

Location

A relative XDG_CONFIG_HOME is ignored, as the XDG spec requires. The same rule applies on every platform, including macOS (not ~/Library).

Create it

bakefile init without -g always creates in the current directory (or -C), never in a parent or the global directory.

Keep it in a dotfiles repo

Symlink the repo to the global directory (instead of bakefile -g init; if ~/.config/bake already exists, ln -s would create the link inside it). Commands run in the real repo directory, so its relative paths and bakefile.py.lock work:

Run global commands

Outside any project, plain bake <command> falls back to the Global bakefile.py. Inside a project with its own bakefile.py, use -g:
-g -f picks another file in the global directory, so one repo can hold several global Bakebooks:
-g together with -C is a usage error. bake -g and bakefile -g subcommands with no Global bakefile.py name the expected path and suggest bakefile -g init.

Manage it

Every bakefile subcommand takes -g. For a Global bakefile.py with PEP 723 inline metadata:

Acting on the Invocation directory

Since commands run in the bakefile.py’s directory, a command that should act where you called bake from reads self.ctx.invocation_dir. It stays correct when bake re-runs itself under the bakefile.py’s Python. For example, a global command that cleans Python caches under the current directory:
See Context.

Upgrading

Earlier versions only looked in the current directory (or -C). Now, running bake from a subfolder without its own bakefile.py runs the parent’s commands instead of failing. Use -C <dir> when you want exactly one directory.
Last modified on November 22, 2026