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:
|
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 ( |
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 |
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_versioninayx_workspace.jsonis 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.13Create 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 --versionUpgrade
pip install ayx_plugin_cli --upgradeThe CLI prints a warning at startup when a newer release is available.
Uninstall
pip uninstall ayx_plugin_cliUninstalling 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.