# Installation

This page explains how to install `dbnomics-toolbox` to a Python project.

## Prerequisites

- Python 3.12+
- Git
- optional (but recommended): [`uv`](https://docs.astral.sh/uv/)

```{note}
`uv` is a modern Python project management tool that handles virtual environments and dependencies for you.
We recommend using it for a smoother experience, but you can also use `pip` and `venv` if you prefer.

In particular, `uv`:
- manages the dependencies of the project, updating the `pyproject.toml` and `uv.lock` files when you add or remove packages,
- manages the virtual environment of the project (creation, activation, etc.),
- allows specifying the version of Python to use for the project, and installing it automatically if not available on the system.
```

## Installation options

::::{tab-set}
:::{tab-item} uv
:sync: uv
:selected:

Create a new Python project with `uv` (skip if you already have one):

```bash
mkdir my-project
cd my-project
uv init
```

### Install from PyPI

```bash
uv add dbnomics-toolbox
```

### Install from source (remote)

```bash
cd my-project
uv add git+https://git.nomics.world/dbnomics/dbnomics-toolbox.git
```

### Install from source (local)

```bash
mkdir vendor
git clone https://git.nomics.world/dbnomics/dbnomics-toolbox.git
cd ../my-project
uv add --editable ../vendor/dbnomics-toolbox
```

:::

:::{tab-item} pip
:sync: pip

Create a new Python project with a virtual environment (skip if you already have one):

```bash
mkdir my-project
cd my-project
python -m venv .venv
source .venv/bin/activate
```

### Install from PyPI

```bash
pip install dbnomics-toolbox
```

### Install from source (remote)

```bash
cd my-project
pip install git+https://git.nomics.world/dbnomics/dbnomics-toolbox.git
```

### Install from source (local)

```bash
mkdir vendor
git clone https://git.nomics.world/dbnomics/dbnomics-toolbox.git
cd ../my-project
pip install --editable ../vendor/dbnomics-toolbox
```

:::
::::

## Validate the installation

Check that Python can import the package:

::::{tab-set}
:::{tab-item} uv
:sync: uv
:selected:

```bash
cd my-project
uv run python -c "import dbnomics_toolbox; print('OK')"
```

:::

:::{tab-item} pip
:sync: pip

```bash
cd my-project
python -c "import dbnomics_toolbox; print('OK')"
```

:::
::::

If this command prints `OK`, your environment is ready.

## Next step

Continue with the [](tutorial/index.md).