Additional Nexus reference PDFs:

Nexus legacy documentation:

This information is for Vicon Nexus 2.14. For up-to-date help, see the latest Nexus documentation.

Vicon Nexus banner

The Nexus API is supplied as a Python package called viconnexusapi and is automatically installed with Nexus. The build of Python installed within Nexus is Python 3. You can run the Python SDK for Nexus in a Python 3 environment as well as in a Python 2 environment.

For more information, see:

Configure Python for scripting with Nexus

To set up Python to work with Nexus:

  1. Go to Windows Search and start to type Python.
  2. Click the required Python.
  3. To automatically configure Python for scripting with Nexus, at the command prompt, enter the following
from viconnexusapi import ViconNexus
vicon = ViconNexus.ViconNexus()

import viconnexusapi
vicon = viconnexusapi.ViconNexus.ViconNexus()

The Python installed with Nexus contains the API version shipped with that version. However, if you install the package into another Python distribution, you are responsible for installing the appropriate version.

For information on how to access the help provided on the relevant Python commands, see Python commands for use with Nexus. For more information about how to use Python, see

If you disconnect your Ethernet cable and turn off wifi, when you enter a Python command, the following error may be displayed:
Host Application is not connected, unable to retrieve command list
This is because Python connects to Nexus over TCP/IP and if you are working entirely offline, Python and Nexus cannot connect.
To solve this issue, install the Microsoft Loopback Adapter. For instructions on how to do this, see Install the Microsoft loopback adapter.

Run a Python script from within Nexus

In the Communications pane, the Python tab enables you to set the path to your Python installation and run a script without having to include it in a pipeline operation.

To run a Python script:

  1. On the Python tab, ensure the Advanced properties are displayed.
  2. In the Python script file field, enter or browse to the full path and filename of the Python script you want to run.
  3. In the Script arguments field, enter any arguments needed by the Python script you specified.
  4. In the Python command field, select the required Python (for an explanation of the options, see Launch the required Python). The default is python.exe.
  5. If the Python installation you want to use is not in the PATH, in field, in the the Environment activation field, enter or browse to the full path name of executable file (usually a .bat file) that will run in the command shell to configure your Python environment before running the Python script that you specified in the Python script file field. The executable should run the commands needed to activate the virtual environment, which could include changing directories, configuring PATH, etc.
    By default, the Environment activation file is the supplied NexusLocalPython.bat file.
    This sets the PATH environment to point to the Python installation provided by Nexus.
  6. If you want to launch a Python shell, using the selected Python, click Python shell.
  7. To run the specified script, click Run Script.

To create a new pipeline that contains all the above properties with the values you specified, click Create Pipeline.

Note that the settings in the Python Script Interface persist between runs, and the settings for Python command and Environment activation are used as the initial values when you create a Run Python Operation pipeline operation. If you change the parameters for a specific operation in a pipeline, they do not affect the persisted values of the parameters and they do not alter the values of the settings on the panel.

Install the Nexus API into other Python distributions

The build of Python (Python 3) installed within Nexus automatically installs the viconnexusapi package as part of Nexus. A script is also available with the installer, which installs the package into the system Python distribution. You can also directly install the package into any other Python distributions that you have installed.

cd "C:\Program Files\Vicon\Nexus2.14\SDK\Win64\Python"
# install the api into the system python
# install the api into a specific python distribution
<path to user python> -m pip install ./viconnexusapi

The advanced modeling scripts are provided as a package called viconnexusutils and are available in the same way as viconnexusapi, except that these scripts are not automatically installed. This is because they have additional dependencies that cannot be guaranteed to be present and must be downloaded by pip.

Launch the required Python

The shell launched by the python operation is either the Python distribution shipped with Nexus or your default Python (as determined by the PATH variable).

If the Python distribution shipped with Nexus is launched, the API package is automatically available for import, and additional scripts are not required.

If you choose to use a Python that is different from the installed Nexus distribution, you can use an advanced option to select the command used to launch Python. The options for this are python.exe or py.exe:

  • If you have only a Python 2 or a Python 3 installation in the path, python.exe launches that version of Python.
  • If you have both versions and the pylauncher utility, py.exe launches either Python 2 or Python 3, depending on a shebang comment at the start of the launched script.

CGM2 Python version

CGM2 launches using the version of Python 3 installed with Nexus. 

Note that:

  • To ensure pyCGM2 continues to operate correctly, do not modify the Python installation that is installed with Nexus.
  • Do not use versions of pyCGM2 other than that supplied by Vicon. Using other versions of pyCGM2 may cause Nexus operations to fail.
    (If you want to use a different version of pyCGM2 for comparison purposes, create pipelines with the Environment activation file set appropriately in the pipeline operation(s).)
  • If you customize your Python environment, note that it is assumed that the Scripts folder that contains the pyCGM2 scripts is the current folder after the Environment activation file has finished running.

Install the Microsoft loopback adapter

To install the Microsoft loopback adapter on Windows 10:

  1. Right-click the Windows Start menu icon and select Device Manager (or use your preferred method of opening the Device Manager).
  2. In the Device Manager, click the Action menu and then select Add legacy hardware.

  3. On the welcome screen, click Next.
  4. In the Add Hardware screen, select Install the hardware that I manually select from a list and then click Next
  5. In the next screen, scroll down the Common hardware types list, select Network adapters and then click Next.

  6. From the Manufacturer list, select Microsoft, and then select Microsoft KM-TEST Loopback Adapter card model and click Next.

  7. In the next screen, click Next.
  8. Click Finish.