# Installation

PipeWhy is a development candidate, version **0.1.0.dev0**, with proprietary
package metadata. The [PyPI project](https://pypi.org/project/pipewhy/) lists
published versions. Use `python -m pip install --pre pipewhy` for prereleases;
the instructions below also support source checkouts and locally built wheels. Python **3.14** is required; current
qualification uses CPython 3.14.7. Poetry **2.5.x** manages the local environment.

## From the source checkout

Run from the repository root:

```console
poetry config virtualenvs.in-project true --local
poetry sync
poetry run pipewhy --help
poetry run pipewhy --version
```

The first command places the environment in `.venv`. Use your tool environment's
Poetry executable if `poetry` is not on PATH.

To enable the optional native CPU backend and Enron connector:

```console
poetry sync --extras cpu --extras enron
```

Use `--extras cuda` only when configuring the experimental CUDA backend. Read
its [hardware and runtime requirements](../user_guide/cuda.md) first. Poetry
`sync` removes extras not selected in that invocation; include every extra you
intend to keep. Development dependencies include PyArrow and NumPy for tests;
they are not dependencies of the core wheel.

## Install a locally built wheel

```console
poetry build
python -m venv .artifacts/consumer-venv
```

Use the new environment's Python executable to install the wheel. On Windows:

```powershell
.artifacts/consumer-venv/Scripts/python.exe -m pip install dist/pipewhy-0.1.0.dev0-py3-none-any.whl
.artifacts/consumer-venv/Scripts/pipewhy.exe --help
```

On Linux, replace `Scripts/python.exe` with `bin/python` and `Scripts/pipewhy.exe`
with `bin/pipewhy`. To install extras, quote the wheel path with its extra selector:
`"dist/pipewhy-0.1.0.dev0-py3-none-any.whl[cpu,enron]"`.

Fixtures and the Enron corpus are not bundled in the wheel. An installed package
needs explicitly configured external source data. See the
[fixture guide](../user_guide/fixtures.md) and [Enron guide](../user_guide/enron.md).

## Read the documentation

Install the separate documentation group and build the site:

```console
poetry sync --with docs
poetry run python tools/build_docs.py
poetry run python -m http.server 8000 --bind 127.0.0.1 --directory docs/_build/html
```

Open <http://127.0.0.1:8000/> while the server is running. The HTML entry point
is `docs/_build/html/index.html`; the portable archive is `dist/pipewhy-docs.zip`.