.. index:: Get started

.. _getting_started:

Getting Started
===============

Requirements
-----------

Bio-pype requires:

- Python 3.4 or later
- PyYAML, psutil, rich, semantic-version (installed automatically with pip)

Installation
-----------

Using Virtual Environments
^^^^^^^^^^^^^^^^^^^^^^
We strongly recommend using virtual environments::

    python -m venv bio_pype_env
    source bio_pype_env/bin/activate

From PyPI
^^^^^^^^
For most users, installing from PyPI is recommended::

    pip install bio-pype

From Source
^^^^^^^^^
For latest features or development::

    git clone https://codeberg.org/bio-pype/bio-pype
    cd bio-pype
    pip install .

Quick Start: Using Workflows from the Registry
----------------------------------------------

The fastest way to get started is to install a workflow from the registry.
No manual directory setup is required.

1. **Sync the registry** to discover available workflows::

    pype registry sync

2. **Search for workflows**::

    pype registry search

3. **Install a workflow** (replace ``somatic`` with any workflow name from the search)::

    pype registry install somatic

4. **Set PYPE_MODULES** to activate the installed workflow. Use ``pype registry path``
   to get the path for a specific version::

    export PYPE_MODULES=$(pype registry path somatic==2026.03.11-1)

5. **Set up your execution profile** (the profile stores paths to reference data,
   software, and system settings).

   If the workflow ships a profile **spec** (a ``.yaml.spec`` file), let Bio_pype
   fetch and build everything for you — no manual editing needed::

    pype profiles build hg38 --ref-dir /data/references

   Otherwise, edit an existing profile to point at resources you already have::

    pype profiles edit hg38

6. **Run a pipeline**::

    pype run my_pipeline --sample sample_name --project_dir /scratch/project

When a spec is available, :ref:`building_profiles` is the recommended path — it
downloads and builds the reference files and pulls the software automatically, so
you can skip ``pype profiles edit`` entirely. For pipeline execution options, see
:ref:`run`.

Manual Setup (Advanced)
----------------------

If you are developing your own workflows rather than installing from the registry,
create a directory structure for your snippets, pipelines, and profiles, then
point bio-pype to them via configuration:

1. Create module directories::

    mkdir -p ~/bio_pype_modules/{snippets,pipelines,profiles}

2. Create configuration file ``~/.bio_pype/config``::

    PYPE_MODULES=~/bio_pype_modules

Alternatively, point to individual directories::

    PYPE_SNIPPETS=~/bio_pype_modules/snippets
    PYPE_PIPELINES=~/bio_pype_modules/pipelines
    PYPE_PROFILES=~/bio_pype_modules/profiles

For detailed configuration options, see :ref:`configuration`.

.. _virtualenv: https://virtualenv.pypa.io
.. _python package index: https://pypi.org