<br />

There are a few ways to set up your environment to use TensorFlow Quantum (TFQ):

- The easiest way to learn and use TFQ requires no installation---run the [TensorFlow Quantum tutorials](https://www.tensorflow.org/quantum/tutorials/hello_many_worlds) directly in your browser using [Google Colab](https://colab.research.google.com/github/tensorflow/quantum/blob/master/docs/tutorials/hello_many_worlds.ipynb).
- To use TensorFlow Quantum on a local machine, install the TFQ package using Python's pip package manager.
- Or build TensorFlow Quantum from source.

TensorFlow Quantum is supported on Python version 3.10 through 3.12 and depends directly on [Cirq](https://github.com/quantumlib/Cirq).

## Pip package

### Requirements

- pip 19.0 or later (requires `manylinux2014` support)
- [TensorFlow == 2.19.1](https://www.tensorflow.org/install/pip)

See the [TensorFlow install guide](https://www.tensorflow.org/install/pip) to
set up your Python development environment and an (optional) virtual environment.

Upgrade `pip` and install TensorFlow

      pip install --upgrade pip
      pip install tensorflow2.19.1 tf-keras2.19.0
      export TF_USE_LEGACY_KERAS=1

<br />

### Install the package

Install the latest stable release of TensorFlow Quantum:

      pip install -U tensorflow-quantum

> [!TIP]
> **Success:** TensorFlow Quantum is now installed.

## Build from source

The following steps are tested for Ubuntu-like systems.

### 1. Set up a Python 3 development environment

We will use Python 3.10 as an example. First, we need the Python 3.10 development tools.

      sudo apt update
      sudo apt-get install pkg-config zip g++ zlib1g-dev unzip python3.10
      sudo apt install python3.10 python3.10-dev python3.10-venv python3-pip
      python3.10 -m pip install --upgrade pip

<br />

### 2. Create a virtual environment

Go to your workspace directory and make a virtual environment for TFQ development.

      python3.10 -m venv quantum_env
      source quantum_env/bin/activate

<br />

Make sure that the virtual environment is activated for the rest of the steps
below, and every time you want to use TFQ in the future.

### 3. Install Bazel

As noted in the TensorFlow
[build from source](https://www.tensorflow.org/install/source#install_bazel)
guide, the [Bazel](https://bazel.build/)
build system will be required.

Our latest source builds use TensorFlow 2.19.1. To ensure compatibility we use
the same version of `bazel`, 6.5.0. To remove any existing version of Bazel:

      sudo apt-get remove bazel

<br />

Download and install `bazel` version 6.5.0:

      wget https://github.com/bazelbuild/bazel/releases/download/6.5.0/bazel_6.5.0-linux-x86_64.deb

      sudo dpkg -i bazel_6.5.0-linux-x86_64.deb

To prevent automatic updating of `bazel` to an incompatible version, run the following:

      sudo apt-mark hold bazel

Finally, confirm installation of the correct `bazel` version:

      bazel --version

### 4. Build TensorFlow from source

TensorFlow Quantum is compatible with TensorFlow version 2.19.1. To build
TensorFlow from sources, download the [TensorFlow
source code](https://github.com/tensorflow/tensorflow) by cloning the git repository, then switch to the `r2.19`
branch:

      git clone https://github.com/tensorflow/tensorflow.git
      cd tensorflow
      git checkout r2.19

Be sure the virtual environment you created in step 2 is activated, then follow
the TensorFlow instructions for how to [build and install the pip
package](https://www.tensorflow.org/install/source#build_and_install_the_pip_package)
on your system.

> [!NOTE]
> **Note:** it may take over an hour to build TensorFlow.

After the build is complete, and you have installed the pip package, leave the
TensorFlow directory before moving on to step 5:

      cd ..

### 5. Download TensorFlow Quantum

We use the standard [fork and pull request workflow](https://guides.github.com/activities/forking/) for contributions. After forking from the [TensorFlow Quantum](https://github.com/tensorflow/quantum) GitHub page, download the source of your fork and install the requirements:

      git clone https://github.com/username/quantum.git
      cd quantum
      pip install -r requirements.txt

### 6. Build and install TensorFlow Quantum

Be sure the virtual environment you created in step 2 is activated. Then, run
the command below to install the TensorFlow Quantum dependencies:

      pip install -r requirements.txt

Next, use TensorFlow Quantum's `configure.sh` script to configure the TFQ
build:

      ./configure.sh

The `configure.sh` script detects your Python interpreter and sets up a Bazel
toolchain. If you need to manually specify a Python interpreter, you can do so
by passing the `--python` flag or by setting the `PYTHON_BIN_PATH` environment
variable:

      ./configure.sh --python=/path/to/python

> \[!TIP\]
> You can also bypass manual configuration by passing the Python path directly
> to Bazel using `--repo_env=PYTHON_BIN_PATH=/path/to/python`.

Now build TensorFlow Quantum:

      bazel build -c opt --cxxopt="-O3" --cxxopt="-march=native" release:build_pip_package

Before importing `tensorflow` or `tensorflow_quantum`, make sure the
`TF_USE_LEGACY_KERAS=1` environment variable is set so TensorFlow uses the
`tf-keras` package instead of Keras 3.

After the build is complete, run the next two commands to create a Python
package for TensorFlow Quantum and write it to a temporary directory (we use
`/tmp/tfquantum/` in this example), then install it using pip:

      bazel-bin/release/build_pip_package /tmp/tfquantum/
      pip install /tmp/tfquantum/name_of_generated_wheel.whl

To confirm that TensorFlow Quantum has successfully been installed, you can run the tests:

      ./scripts/test_all.sh

<br />

> [!TIP]
> **Success:** TensorFlow Quantum is now installed.