Installation
============

The FieldView Python package is bundled with FieldView and is loaded at
runtime by FieldView. You can use it directly from the bundled path, or
optionally install a matching wheel with ``pip`` into a user/venv location.

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

- FieldView installed on your system.
- A Python runtime that matches one of the bundled module versions
  (FieldView ships multiple versions under ``pyfieldview/pythonXY``).
- Supported Python versions: 3.10 through 3.14.

.. note::

   On Windows, PyFieldView requires a standard Python
   installation and does not support Microsoft Store Python. Download
   and install Python from `python.org <https://www.python.org/>`_.

If FieldView cannot detect your Python runtime
----------------------------------------------

At startup, FieldView looks for Python in your shell ``PATH``
(``python3``/``python``).

If Python is not found in ``PATH``, set ``PYTHONHOME`` to the Python
installation you want FieldView to use, then launch FieldView from the same
shell.

On Windows, you can do the same from ``cmd.exe`` or PowerShell before launching
``fv.bat``, or define ``PYTHONHOME`` in the system/user environment settings if
you want that Python runtime to be used consistently.

Example (macOS, Homebrew Python 3.13):

.. code-block:: bash

   PYTHONHOME=/opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/ \
   /Applications/FieldView-2025.0.2.app/Contents/MacOS/fv

Example (Windows PowerShell):

.. code-block:: powershell

   $env:PYTHONHOME = "C:\Users\you\AppData\Local\Programs\Python\Python311"
   & "C:\Program Files\Tecplot\FieldView 2025.0.12\bin\fv.bat"

In some setups, both supported and unsupported Python versions are installed,
but your shell resolves ``python3``/``python`` to the older unsupported one
first (for example, Python 3.9). In that case, startup can fail even though a
supported Python version is available on the same system.

Linux example (multiple Python installs):

.. code-block:: bash

   which -a python3 python
   python3 --version
   python --version

If those commands show that ``python3`` or ``python`` points to an unsupported
version, you can:

1. Launch FieldView with a supported Python first in ``PATH``.

   .. code-block:: bash

      PATH=/opt/python/3.11/bin:$PATH /path/to/fv

2. Or set ``PYTHONHOME`` to a supported Python runtime before launching.

   .. code-block:: bash

      PYTHONHOME=/opt/python/3.11 /path/to/fv



Using FieldView's bundled module
--------------------------------

When you run a script with FieldView (for example via ``-python`` or the
``Execute Python File`` menu), FieldView sets up the import path so that
``import fieldview`` works automatically. If a user-local site-packages install
is present, FieldView checks that location first and then falls back to the
bundled ``<FV_HOME>/pyfieldview/pythonXY`` path. A warning is printed when the
bundled version is newer than the user-local version.

Using PyFieldView from user-local Python packages (IDE/autocomplete)
---------------------------------------------------------------------

In some workflows, installing PyFieldView in a user-level Python environment
can simplify IDE integration, especially when the IDE is already configured to
use that interpreter for code completion, linting, and source navigation.

In that case, install a matching bundled wheel with that same
interpreter:

FieldView builds and ships per-version wheel files under:

``<FV_HOME>/pyfieldview/wheels``

Install the wheel that matches your Python runtime:

.. code-block:: bash

   # Example for Python 3.10 (cp310). Use cp311/cp312/... for other versions.
   python -m pip install --user "<FV_HOME>/pyfieldview/wheels/fieldview-*-cp310-*.whl"

.. code-block:: powershell

   # Windows PowerShell example for Python 3.11 (cp311).
   py -3.11 -m pip install --user "$env:FV_HOME\pyfieldview\wheels\fieldview-*-cp311-*.whl"

In a virtual environment, omit ``--user``.

To confirm wheel compatibility, check the tags supported by your active Python
interpreter and make sure they match the wheel filename tag (for example,
``cp311``):

.. code-block:: bash

   python -m pip debug --verbose

If you are using FieldView's bundled module directly (no pip install), point
your IDE to the bundled path for autocomplete:

1. Locate the bundled module folder that matches your Python version:

   ``<FV_HOME>/pyfieldview/python311`` (example)

2. Add that folder to your IDE's Python search path.

   - VS Code: ``python.analysis.extraPaths`` (example)

Verify the install
------------------

Run this in a FieldView Python script:

.. literalinclude:: _examples/installation_verify_example.py
   :language: python
   :emphasize-lines: 4

If the install is working correctly, the script should print the path to the
imported PyFieldView module. Use that path to confirm whether FieldView is
using the bundled module or a user-installed package. Where this output
appears depends on how FieldView was launched and on your operating system:
if FieldView was started from a terminal on Linux or macOS, or from Command
Prompt/PowerShell on Windows, the output is printed in that shell window. If
FieldView was started directly from the GUI and no shell is attached, the
output appears in the FieldView console output area instead.