CLI Reference

python -m appimage.ctl COMMAND [OPTIONS]

Always the interpreter you meant - same reasoning as python -m pip over a bare pip. There’s no separate appimagectl console script: that would resolve to whichever install happens to be first on PATH, not necessarily the one you’re actually working in.

COMMAND is required - check, build, init, lock, enable-reproducible, build-appdir, and update-tools are each a distinct, mutually exclusive action.

Commands

Command	Description
build	Build the AppImage.
check	Show detected build configuration and exit without building.
init	Write auto-detected values to [tool.appimage] in pyproject.toml (only missing keys) and exit. Resolves the latest python-build-standalone release to write python_date/python_sha256 (a lightweight API call, no download), and resolves appimagetool and the runtime file (possibly downloading them, ~8 MB + ~1 MB) to write appimagetool_version/appimagetool_sha256/runtime_sha256, whichever of these aren’t already set.
lock	Generate hash-pinned lock files and exit - a thin wrapper around pip lock, run through the bundled interpreter (see Verified dependencies). Generates pylock.toml for third-party dependencies and a build-backend lock file for the packaged project’s own [build-system].requires in the same run, writing pylock/build_pylock to pyproject.toml for whichever isn’t already set.
enable-reproducible	One-command onboarding: runs init then lock, then a real build with reproducible enforced - and only once that build succeeds, writes reproducible = true to pyproject.toml. See Getting to full reproducibility.
build-appdir	Assemble the AppDir - install Python and packages, copy assets/extra files, run hooks, compile bytecode, scrub build-machine paths - without resolving appimagetool/the runtime stub or packaging into an .AppImage. The result is a complete, runnable installation tree usable for testing or deploying some other way. Only enforces the AppDir-side reproducibility pin (python_date/python_dir), not appimagetool_sha256/runtime_sha256 - those are irrelevant here since packaging never runs.
update-tools	Move every toolchain pin forward to whatever’s currently available - python_date, appimage_version/appimage_sha256, appimagetool_version/appimagetool_sha256, runtime_sha256, and appimagectl_version - overwriting what’s already configured. Unlike init, which only fills in what’s missing. Leaves pylock/build_pylock (regenerate those with lock) and project metadata untouched.

Options

Shared by every command above (a command-specific note is called out where one applies):

Option	Description
--app NAME	Override the application name.
--entry-point EP	Override the console script entry point.
--python VERSION	Override the Python version to bundle (e.g. 3.13).
--python-date DATE	Override the python-build-standalone release date for reproducible builds (e.g. 20260211).
--extras EXTRA	Override extras to install (e.g. production). May be repeated.
--package TARGET	Additional pip install target. May be repeated.
--project-dir PATH	Path to the project root (default: current directory).
--appimagetool PATH	Path to a local appimagetool binary. Skips the build cache and download - PATH itself is never searched, see Classic appimagetool detected.
--appimagetool-version LABEL	Informational label for the pinned appimagetool build.
--appimagetool-sha256 SHA256	Expected sha256 of the appimagetool binary, verified regardless of how it was resolved.
--python-archive PATH	Path to a local python-build-standalone tarball. Skips the download.
--python-sha256 SHA256	Expected sha256 of the python-build-standalone tarball.
--appimage-version VERSION	Exact version of the bundled appimage runtime module to install (overrides pyproject.toml). Empty resolves to the version of appimage.ctl currently doing the build.
--appimage-sha256 SHA256	Expected sha256 of the appimage runtime module wheel for appimage_version. When empty, the digest PyPI publishes for that release is looked up and used instead.
--runtime-file PATH	Path to a local AppImage runtime ELF stub, passed to appimagetool as --runtime-file. Skips the download.
--runtime-sha256 SHA256	Expected sha256 of the runtime file, verified regardless of how it was resolved.
--verify-downloads	Abort the build instead of warning whenever appimagetool, the runtime file, or the Python archive would otherwise be used unverified.
--require-zsyncmake	Abort the build instead of warning when update_info is set but appimagetool didn’t produce a .zsync file (checked after packaging, against the real output - see Configuration).
--pylock PATH	Path to a hash-pinned pylock.toml for third-party dependencies. Generate it with lock.
--require-pylock	Abort the build instead of warning when pylock is not set.
--build-pylock PATH	Path to a hash-pinned pylock-format file constraining the packaged project’s own [build-system].requires, so pip’s isolated build environment for it is hash-verified too. Generate it with lock, alongside pylock.toml - see Verified build backend.
--require-build-pylock	Abort the build instead of warning when build_pylock is not set.
--uploaded-prior-to PnD	Only meaningful on lock/enable-reproducible: passed through to pip lock --uploaded-prior-to as a cooldown window (e.g. P7D excludes packages published in the last 7 days) - gives the community time to catch a compromised release before it gets locked in. Applies to both lock files generated.
--reproducible	Enforce a build that’s reproducible across machines and over time: implies --verify-downloads and --require-zsyncmake, and requires python_date/appimagetool_sha256/runtime_sha256 to already be set (run init first). Does not resolve or write any values itself - for that, see enable-reproducible above. Independent of --pylock/--require-pylock/--build-pylock/--require-build-pylock - opt into dependency and build-backend hash-pinning separately.

Examples

# Build with a specific Python version
python -m appimage.ctl build --python 3.13

# Reproducible build pinned to a specific release date
python -m appimage.ctl build --python-date 20260211

# Override app name and entry point
python -m appimage.ctl build --app myapp --entry-point myapp.cli:main

# Install extras and additional packages
python -m appimage.ctl build --extras production --package extra-lib

# Build from a different project directory
python -m appimage.ctl build --project-dir /path/to/project

# Use a locally installed appimagetool instead of downloading
python -m appimage.ctl build --appimagetool /opt/appimagetool-x86_64.AppImage

# Use a previously downloaded Python archive (e.g. from another build)
python -m appimage.ctl build --python-archive /shared/cache/python.tar.gz

# Fully offline build using local copies of appimagetool, the runtime, and Python
python -m appimage.ctl build \
  --appimagetool /opt/appimagetool-x86_64.AppImage \
  --runtime-file /opt/runtime-x86_64 \
  --python-archive /shared/cache/python-3.11-x86_64.tar.gz

# Pin and verify the toolchain automatically, then build reproducibly
python -m appimage.ctl init   # writes python_date/python_sha256/appimagetool_version/appimagetool_sha256/runtime_sha256
python -m appimage.ctl build

# Fail loudly instead of warning if anything ends up unverified
python -m appimage.ctl build --verify-downloads

# One command: pin the toolchain, hash-pin every dependency, verify with a
# real build, and turn reproducible = true on once that build succeeds
python -m appimage.ctl enable-reproducible

# Piecewise equivalent, plus a one-off enforced build afterwards
python -m appimage.ctl init
python -m appimage.ctl lock
python -m appimage.ctl build --reproducible

# Generate hash-pinned lock files (pylock.toml + build_pylock), then build against them
python -m appimage.ctl lock
python -m appimage.ctl build --require-pylock --require-build-pylock

# Regenerate both locks with a 7-day cooldown, excluding just-published releases
python -m appimage.ctl lock --uploaded-prior-to P7D

# Just assemble the AppDir - for testing, or deploying without packaging
# into a single-file .AppImage. Never touches appimagetool/the runtime stub.
python -m appimage.ctl build-appdir