How `--install-missing` Controls Optional Package Installation in book-to-skill

The --install-missing flag provides three control modes—yes for automatic silent installation, ask for interactive prompts, and no for strict failure—that determine how the extractor handles missing optional dependencies like ebooklib, beautifulsoup4, and pillow.

The virgiliojr94/book-to-skill repository converts e-books into Anki flashcards using modular extraction pipelines that rely on optional third-party libraries. The --install-missing command-line argument governs whether the tool silently installs, interactively requests permission for, or strictly rejects missing packages required for your chosen extraction method.

Parsing the --install-missing Flag in utils.py

The argument parsing logic resides in book_to_skill/utils.py, specifically within the parse_arguments function. Lines 97‑102 extract the flag from the command line and forward the raw arguments to normalize_install_mode on line 611.

The normalize_install_mode function inspects the value supplied to --install-missing and maps it to one of three internal behaviors. This normalization step ensures consistent handling across the codebase before the dependency resolution phase begins.

The Three Installation Modes

Based on the normalized value, the extractor behaves differently when encountering an unmet optional dependency.

Automatic Installation (yes)

When --install-missing yes is specified, the tool enters automatic installation mode. If a required optional package is absent, prepare_dependencies in book_to_skill/dependencies.py executes a silent pip installation using subprocess.run([sys.executable, "-m", "pip", "install", …]). This occurs without user intervention, making it ideal for fresh environments where you want dependencies resolved immediately.

Interactive Mode (ask)

Setting --install-missing ask enables interactive prompting. When a missing dependency is detected, the user receives a prompt asking whether to proceed with installation. If the user confirms, the same subprocess pip installation executes; otherwise, the program raises an ExtractionError and aborts with an informative message.

Strict Mode (no)

Using --install-missing no (or the synonymous --no-install-missing) activates strict mode. The program never attempts to install missing packages. If a required optional dependency is absent, prepare_dependencies immediately raises an ExtractionError, halting execution. This mode is essential for automated pipelines where implicit package installation is undesirable.

Dependency Resolution in dependencies.py

The actual installation mechanism lives in book_to_skill/dependencies.py. Lines 132‑135 detect the installation mode flag, and the subsequent prepare_dependencies implementation invokes the pip subprocess when the mode is yes or when the user consents in ask mode.

This centralized dependency preparation ensures that all extraction paths—whether text, technical, or image-based—handle missing packages consistently according to the user-specified policy.

Command-Line Usage Examples

The scripts/extract.py entry point accepts --install-missing to control the dependency resolution behavior:

# Automatic installation (useful in a clean CI environment)

python3 scripts/extract.py mybook.epub --mode text --install-missing yes

# Interactive – will prompt if a package is missing

python3 scripts/extract.py mybook.epub --mode technical --install-missing ask

# Strict – never try to install, abort if a needed optional package is absent

python3 scripts/extract.py mybook.epub --mode text --install-missing no

Summary

• --install-missing yes triggers silent automatic installation of missing optional dependencies using pip via subprocess.
• --install-missing ask presents an interactive prompt before installing, aborting if the user declines.
• --install-missing no prevents any installation attempts, raising ExtractionError if required packages are missing.
• The flag is parsed in book_to_skill/utils.py (lines 97‑102, 611) and executed in book_to_skill/dependencies.py (lines 132‑135).

Frequently Asked Questions

What values does --install-missing accept?

The flag accepts three string values: yes for automatic installation, ask for interactive confirmation, and no for strict enforcement. Alternatively, you can use the boolean-style flag --no-install-missing as a synonym for --install-missing no.

How does automatic installation work internally?

When mode is set to yes, the prepare_dependencies function in book_to_skill/dependencies.py detects the missing package and executes subprocess.run([sys.executable, "-m", "pip", "install", …]) to install it before proceeding with extraction.

What happens if I use --install-missing no and a dependency is missing?

The program raises an ExtractionError immediately upon detecting the missing optional package (such as ebooklib or pillow) and terminates without attempting installation, ensuring strict environment control.

Can I use --install-missing in non-interactive environments like CI/CD?

Yes. For CI/CD pipelines, use --install-missing yes to allow automatic resolution of dependencies, or --install-missing no to enforce that all dependencies are pre-installed in the environment. Avoid --install-missing ask in non-interactive shells, as it will hang waiting for user input.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}