# How to Override the Default Work Directory for the Book‑to‑Skill Extractor

> Override the default work directory for the Book to Skill extractor by setting the BOOK_SKILL_WORKDIR environment variable to a custom writable path. Learn how now.

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

---

**Set the `BOOK_SKILL_WORKDIR` environment variable to any writable path before invoking the extractor to override the default temporary directory location.**

The Book‑to‑Skill extractor generates intermediate files during document processing, storing them in a dedicated work directory. By default, this location is automatically generated under the system temporary folder using the current process ID. Understanding how to override the default work directory for the extractor allows you to integrate the tool with custom pipelines, persist outputs to specific locations, or manage disk space in constrained environments.

## Understanding the Default Work Directory Behavior

The extractor defines its default output location in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) through the `default_output_dir()` function:

```python
def default_output_dir() -> Path:
    return Path(tempfile.gettempdir()) / f"book_skill_work-{os.getpid()}"

```

This implementation creates a unique subdirectory under the system temporary directory, appending the process ID to prevent collisions between concurrent runs. The extractor uses this path to store [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) and [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json) files during the extraction pipeline.

## Overriding the Work Directory with BOOK_SKILL_WORKDIR

According to the source code in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py), the extractor checks for the `BOOK_SKILL_WORKDIR` environment variable before falling back to the default temporary location:

```python
OUTPUT_DIR = Path(os.environ.get("BOOK_SKILL_WORKDIR") or default_output_dir())

```

When `BOOK_SKILL_WORKDIR` is set to a valid path, the `OUTPUT_DIR` variable uses that exact location instead of the auto-generated temporary directory. This configuration is read at import time, meaning the variable must be set before the `book_to_skill` module loads.

## Practical Implementation Methods

You can override the work directory through several approaches depending on your execution context.

### Shell Environment Export

For persistent sessions where you run multiple extractions, export the variable before invoking the CLI:

```bash
export BOOK_SKILL_WORKDIR=/tmp/my_book_skill_work
python -m book_to_skill extract path/to/document.pdf

```

The extractor will create and write files to `/tmp/my_book_skill_work/` instead of the system temp folder.

### One-Off Command Execution

For single invocations without polluting your shell environment, prefix the command:

```bash
BOOK_SKILL_WORKDIR=/var/tmp/run1 python -m book_to_skill extract book.pdf

```

This approach is ideal for CI/CD pipelines or scripted batch processing where each job requires an isolated work directory.

### Programmatic Override in Python

When embedding the extractor within a larger Python application, set the environment variable before importing or reloading the module:

```python
import os
from book_to_skill import cli

os.environ["BOOK_SKILL_WORKDIR"] = "/home/user/custom_workdir"
cli.main(["extract", "my_book.epub"])

```

Note that because [`config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/config.py) evaluates `OUTPUT_DIR` at import time, you must set the variable before any `book_to_skill` submodules import the configuration.

## Verifying the Active Work Directory

The extractor confirms the resolved work directory at runtime. In [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py), the `extract_multi_source` function prints the final paths upon completion:

```

Workdir -> /tmp/my_book_skill_work
Text    -> /tmp/my_book_skill_work/full_text.txt
Meta    -> /tmp/my_book_skill_work/metadata.json

```

Check this output to verify that your `BOOK_SKILL_WORKDIR` override has taken effect.

## Summary

- The default work directory is auto-generated in the system temp folder using the process ID, defined in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py).
- Set the `BOOK_SKILL_WORKDIR` environment variable to override the default location with any writable directory path.
- The configuration module evaluates the environment variable at import time via `os.environ.get("BOOK_SKILL_WORKDIR")`.
- Override methods include shell exports, inline command variables, or programmatic `os.environ` assignment before module import.
- Verify the active directory by examining the runtime output from [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py).

## Frequently Asked Questions

### What environment variable controls the work directory?

The `BOOK_SKILL_WORKDIR` environment variable controls the extractor's work directory. When set, the value overrides the default temporary directory generated by `default_output_dir()` in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py). The variable is read once at module initialization.

### Does the custom directory need to exist before running the extractor?

The custom directory must exist or be creatable by the running process. The extractor attempts to write [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) and [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json) to the specified path immediately upon execution. Ensure the directory has appropriate write permissions to avoid runtime errors.

### How can I confirm which work directory is being used?

The extractor prints the resolved work directory at the end of the extraction process in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py). Look for output lines beginning with `Workdir ->` followed by the absolute path to verify your override is active.

### Will overriding the work directory affect other configuration settings?

No, overriding the work directory only changes the `OUTPUT_DIR` path variable. Other configuration settings in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py), such as `OUTPUT_TEXT` and `OUTPUT_META` (which define the filenames within the work directory), remain unaffected by the `BOOK_SKILL_WORKDIR` environment variable.