Skip to main content

Set Up Environment

This page covers what you need to install before you build plugins with the AYX Plugin CLI, and how to install it.

Prerequisites

Requirement

Needed For

Notes

Windows

Running the CLI and installing into Designer.

Designer installs plugins under:

  • %APPDATA%\Alteryx\Tools (user)

  • %ALLUSERSPROFILE%\Alteryx\Tools (admin)

Alteryx Designer

Final verification and installation.

Needed to run the plugin as part of a workflow.

Python 3.10 or 3.13

The CLI, the SDK, and the test tooling.

The CLI does not support Python 3.11, 3.12, or 3.14 and later. Refer to the table below.

Node.js 18 or later, with npm

Plugins that have a custom configuration panel.

Not needed for backend-only plugins (--omit-ui).

Match Python to Your Designer Release

The Python version in your development environment should align with the Python runtime embedded in the Designer release you are targeting.

Designer Release

Embedded Python

2025.1, 2025.2

3.10

2026.1 and later (for example, 2026.3)

3.13 (bundled 3.13.x)

Two settings are involved, and they are independent:

  • The local interpreter runs the CLI, pytest, and the test harness. It can be newer than Designer’s.

  • The workspace setting backend_language_settings.python_version in ayx_workspace.json is the version the packaged plugin uses. This one must match the target Designer release.

sdk-workspace-init records the major.minor version of the interpreter that ran it. If that differs from your target Designer release, edit the value, run ayx_plugin_cli generate-config-files, and re-run your tests. Go to Package and Install.

Third-party dependencies listed in backend/requirements-thirdparty.txt must support the Designer Python version, because they are installed for it when you package.

Node.js for Configuration Panels

Install Node 18 or later if a plugin has a custom React/HTML configuration panel. nvm-windows is a convenient way to manage Node versions.

The commands generate-ui, create-ayx-plugin (without --omit-ui), create-yxi (without --omit-ui), and designer-install (without --omit-ui) check for Node and npm and stop with an error if they are missing. The CLI’s own check accepts Node 12 and npm 6.9 as the minimum, but the generated panel project declares Node 18 or later, so use Node 18 or later.

Set Up the Environment with uv

Develop inside a virtual environment. It keeps each project’s dependencies separate, which lowers the risk of building a package that Designer or other users cannot use. These steps use uv.

Install uv and Python

Run in PowerShell:

 # Install uv (if not already installed)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install the target Python version (for example 3.13 for Designer 2026.x)
uv python install 3.13

Create and Activate a Virtual Environment

Create a dedicated .venv in your project folder. --seed makes sure pip is available.

 mkdir C:\dev\<your-plugin-workspace>
cd C:\dev\<your-plugin-workspace>

# Create the virtual environment
uv venv --python 3.13 --seed .venv

# Activate it in PowerShell
.\.venv\Scripts\Activate.ps1

If you prefer Conda or python -m venv, any isolated environment with a supported Python works.

Install the CLI and SDK

With the environment active, upgrade pip and install both packages:

 python -m pip install --upgrade pip

# Install the latest compatible releases
pip install ayx_plugin_cli ayx_python_sdk

For Designer 2026.x with Python 3.13, use ayx_plugin_cli 1.3.2 or later and ayx_python_sdk 2.5.2 or later.

Add pytest if you want to run tests directly with pytest rather than through ayx_plugin_cli test.

Verify the Installation

 ayx_plugin_cli version

This prints Alteryx CLI Version: <version>. If the command is not recognized, the CLI is not installed in the active environment. Activate the correct environment and reinstall.

Optional checks:

 python -c "import ayx_python_sdk; print(ayx_python_sdk.__file__)"
node --version
npm --version

Upgrade

 pip install ayx_plugin_cli --upgrade

The CLI prints a warning at startup when a newer release is available.

Uninstall

 pip uninstall ayx_plugin_cli

Uninstalling removes the commands that create, update, and package plugins. Your workspace files are not deleted, but you cannot manage them with the CLI until you reinstall it.

Next Steps

To create your first workspace and plugin, go to Get Started.