# Configuration



Reyk has two configuration surfaces: `pyproject.toml` that controls how the CLI vendors dependencies,
and parameters on the `isolate_package()` function that control how isolation is applied at runtime.

## `pyproject.toml` configuration [#pyprojecttoml-configuration]

Add a `[tool.reyk]` section to your `pyproject.toml`:

```toml
[tool.reyk]
libraries-path = "libs"
vendor-groups = ["vendor-libs"]
```

All fields are optional and fall back to their defaults if omitted.

### Options [#options]

* **`libraries-path`** (string, default: `"libs"`): Relative path where vendored libraries are installed.
* **`vendor-groups`** (array of strings, default: `["vendor-libs"]`): A list of ` [dependency-groups]` whose packages should be vendored.

## `isolate_package()` configuration [#isolate_package-configuration]

`isolate_package()` is called in your package's **init**.py and installs the import hook at runtime. It accepts two optional parameters:

```py
def isolate_package(
    package_path: Optional[Path] = None,
    vendorized_libs_dir_name: str = "libs",
) -> None:
```

### Parameters [#parameters]

* **`package_path`** (`Path | None`, default: `None`): The path to the package to isolate. When `None`, Reyk automatically detects the directory of the file that called isolate\_package(). In almost all cases you can omit this parameter.
* **`vendorized_libs_dir_name`** (string, default: `"libs"`): The name of the subdirectory inside your package where vendored libraries are stored. This must match the `libraries-path` value in `pyproject.toml`.

## Examples [#examples]

Calling with all defaults - the common case:

```py
from reyk.isolator import isolate_package

isolate_package()
```

Calling with a custom libs directory name:

```py
from reyk.isolator import isolate_package

isolate_package(vendorized_libs_dir_name="vendor")
```

```toml
[tool.reyk]
libraries-path = "vendor"
```

## Keeping both surfaces in sync [#keeping-both-surfaces-in-sync]

The `libraries-path` option in `pyproject.toml` and the `vendorized_libs_dir_name` parameter in `isolate_package()` refer to the same directory.

If these two values do not match, the CLI will vendor packages into one directory while the runtime hook looks in a different directory.
Remember to change both values together.


# Reyk





<HomePageContent />


# Quick Start



## Installation [#installation]

<Callout>
  Reyk uses [uv](https://docs.astral.sh/uv) (v0.6.6>=) for package
  management. Make sure you have uv installed and initialized in your project.
</Callout>

Install Reyk from PyPI:

```bash
uv add reyk
```

## Basic Setup [#basic-setup]

Enable isolation from your package's `__init__.py`:

```python
from reyk.isolator import isolate_package

isolate_package()
```

**That's it!** Inside `your_package`, `import requests` resolves to `your_package.libs.requests`. Outside `your_package`, `import requests` continues to resolve to the normal/global install.

## Vendor Your Dependencies [#vendor-your-dependencies]

Dependencies are defined in `pyproject.toml` under the `[dependency-groups]` section:

```toml
[dependency-groups]
libs = [
    "pydantic~=1.10",
    "requests==2.32.3",
    # ... other dependencies
]
```

The easiest way to manage vendored dependencies is using the [Reyk CLI](../reference/cli).:

```bash
# Add dependencies
uvx reyk-cli add requests==2.32.3 pydantic~=1.10

# Remove dependencies
uvx reyk-cli remove opentelemetry-sdk

# Vendor dependencies into your package
uvx reyk-cli vendor
```

## Project Layout [#project-layout]

A minimal Reyk-enabled package looks like this:

```
your_package/
    __init__.py          # calls isolate_package()
    feature.py           # can `import requests` → uses vendored copy
    libs/
        requests/
            __init__.py
            ...
```

## Next Steps [#next-steps]

You may be interested:

<Cards>
  <Card title="Examples & Use Cases" description="Explore practical examples and use cases for Reyk." href="/docs/examples" />

  <Card title="API Reference" description="Detailed documentation of Reyk's API and CLI." href="/docs/api-reference" />

  <Card title="How Reyk Works" description="Understand the import mechanics behind Reyk." href="/docs/how-it-works/understanding-imports" />
</Cards>


# Reyk CLI





Reyk includes a CLI tool for managing vendored dependencies in your projects.
You can invoke it with `uvx` without adding anything to your dependencies.

<Callout type="tip">
  The CLI requires `uv` to be installed and available in your `PATH`. All
  commands delegate to `uv` under the hood. Install `uv` by following [the
  instructions here](https://docs.astral.sh/uv/getting-started/installation/).
</Callout>

Below are the available commands and their usage.

## `sync` [#sync]

Syncing ensures that all project dependencies are installed and up-to-date with the requirements.

```sh
uvx reyk-cli sync
```

## `add` [#add]

Add a new dependency to your project. This command will install the specified package and update your `pyproject.toml` file.

```sh
uvx reyk-cli add [PACKAGES...] [UV_OPTIONS]
```

### Options [#options]

You can pass any arguments [supported by uv](https://docs.astral.sh/uv/reference/cli/#uv-add).

* `--group [GROUP]`: Add the requirements to the specified dependency group. The group must already exist in [your configuration](../configuration). Defaults to `vendor-libs`.

### Example [#example]

```sh
uvx reyk-cli add requests~=2.33
```

## `remove` [#remove]

Remove an existing dependency from your project. This command will uninstall the specified package and update your `pyproject.toml` file.

```sh
uvx reyk-cli remove [PACKAGES...]
```

### Options [#options-1]

You can pass any arguments [supported by uv](https://docs.astral.sh/uv/reference/cli/#uv-remove).

* `--group [GROUP]`: Remove the packages from the specified dependency group. The group must already exist in [your configuration](../configuration). Defaults to `vendor-libs`.

### Example [#example-1]

```sh
uvx reyk-cli remove requests
```