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

> Learn how book-to-skill's --install-missing flag manages optional package installation with yes ask or no modes. Control missing ebooklib beautifulsoup4 and pillow dependencies effectively.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: how-to-guide
- Published: 2026-08-24

---

**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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) entry point accepts `--install-missing` to control the dependency resolution behavior:

```bash

# 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) (lines 97‑102, 611) and executed in [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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.