##############################
Install with uv
##############################

.. sidebar::

    .. contents::
        :local:
        :depth: 2

``uv`` is a fast Python package and environment manager. It can download the right Python version for you, so you do not need Python 3.12 pre-installed.

Install uv
==========

Install ``uv`` system-wide. This is a one-time step.

.. tabs::

   .. group-tab:: Linux

      .. code-block:: bash

         curl -LsSf https://astral.sh/uv/install.sh | sh

      Then restart your terminal, or run:

      .. code-block:: bash

         source ~/.local/bin/env

   .. group-tab:: Windows

      .. code-block:: powershell

         powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

      Restart your terminal after installation so ``uv`` is on your PATH.

Verify the install:

.. code-block:: bash

    uv --version

Create a Virtual Environment
=============================

``uv`` can download Python 3.12 automatically if it is not already present:

.. tabs::

   .. group-tab:: Linux

      .. code-block:: bash

         uv venv .venv --python 3.12 --seed
         source .venv/bin/activate

   .. group-tab:: Windows

      .. code-block:: powershell

         uv venv .venv --python 3.12 --seed
         .venv\Scripts\Activate.ps1

The ``--seed`` flag installs ``pip`` and ``setuptools`` into the environment so you can use ``pip`` inside it.

Install HOOPS AI
================

With the environment activated, use ``uv pip`` to install. ``uv pip`` always targets the active virtual environment, regardless of any system or Conda paths.

.. note::

    The ``--index-strategy unsafe-best-match`` flag is required. By default, ``uv`` stops at the first index where a package name is found and never checks the others. Without this flag, packages like ``hoops-ai`` or PyTorch GPU wheels that only exist on the extra indexes would be missed or resolved from the wrong source. This flag makes ``uv`` check all indexes and pick the best available version, matching the behaviour of ``pip``.

CPU
---

.. tabs::

   .. group-tab:: Linux

      .. code-block:: bash

         uv pip install "hoops-ai[all]" \
             --extra-index-url https://packages.techsoft3d.com/pip \
             --extra-index-url https://download.pytorch.org/whl/cpu \
             --index-strategy unsafe-best-match

   .. group-tab:: Windows

      .. code-block:: powershell

         uv pip install "hoops-ai[all]" `
             --extra-index-url https://packages.techsoft3d.com/pip `
             --extra-index-url https://download.pytorch.org/whl/cpu `
             --index-strategy unsafe-best-match

GPU (CUDA 13.0)
---------------

.. tabs::

   .. group-tab:: Linux

      .. code-block:: bash

         uv pip install "hoops-ai[all]" \
             --extra-index-url https://packages.techsoft3d.com/pip \
             --extra-index-url https://download.pytorch.org/whl/cu130 \
             --index-strategy unsafe-best-match

   .. group-tab:: Windows

      .. code-block:: powershell

         uv pip install "hoops-ai[all]" `
             --extra-index-url https://packages.techsoft3d.com/pip `
             --extra-index-url https://download.pytorch.org/whl/cu130 `
             --index-strategy unsafe-best-match

``cu130`` corresponds to CUDA 13.0, which is the configuration HOOPS AI is tested against. If you need a different CUDA version, replace ``cu130`` with the appropriate tag. The `PyTorch installation page <https://pytorch.org/get-started/locally/>`__ lists all available index tags for each PyTorch release.

.. note::

    ``hoops-ai[all]`` installs the full stack including CAD access, ML, visualization, notebooks, and the converter. If you only need a subset, see the Extras table on the :doc:`main install page <evaluate>`.

Verify the Installation
========================

.. code-block:: bash

    python -c "import hoops_ai; print(hoops_ai.__version__)"

For a GPU environment, also confirm PyTorch sees your GPU:

.. code-block:: bash

    python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

Next Step
=========

If you plan to use notebooks, register your virtual environment as a Jupyter kernel. See **Registering the Jupyter Kernel** on the :doc:`main install page <evaluate>`.