Skip to main content

Package and Install

This page describes how to turn a workspace into something Designer can run: build a YXI, install it for yourself or for all users, and use --dev installs to iterate quickly.

Choose a Command

Situation

Command

You need a shareable .yxi file.

create-yxi

You are iterating locally and want the plugin in Designer now.

designer-install

You already have a .yxi to install.

install-yxi

 ayx_plugin_cli create-yxi
ayx_plugin_cli designer-install --install-type user
ayx_plugin_cli install-yxi --yxi-path path\to\DemoPackage.yxi --install-type user

For details on CLI command flags, go to Command Reference.

Before You Build

  1. Confirm the target Designer release and set backend_language_settings.python_version to its embedded Python (go to Set Up Environment). Run generate-config-files after changing it.

  2. Run ayx_plugin_cli test.

  3. If any plugin has a configuration panel, confirm Node and npm are installed. Packaging builds the panel first.

  4. List every third-party import in backend/requirements-thirdparty.txt. Anything missing there is missing at runtime in Designer.

Build a YXI with create-yxi

create-yxi builds build/yxi/<package name>.yxi from the whole workspace. The package contains each plugin’s configuration XML, manifest, and icon, the built configuration panel (unless --omit-ui), and the back end with its dependencies. The workspace needs at least one plugin.

To install a YXI by hand, double-click it or drag it into Designer.

Install from Source with designer-install

designer-install runs the same build as create-yxi, then installs the result. During development, this saves you from repackaging and reinstalling manually after each change.

Option

Effect

--install-type user (default)

Installs to %APPDATA%\Alteryx\Tools. Affects the current user.

--install-type admin

Installs to %ALLUSERSPROFILE%\Alteryx\Tools. Affects all users on the machine and needs admin access.

--omit-ui

Builds without configuration panels.

--dev

Development install, described below.

If a plugin with the same name is already installed, the CLI asks before overwriting it. Restart Designer after the first install and after any change to ayx_workspace.json.

--dev Installs

A --dev install does not bundle Python dependencies into the package. The installed plugin finds them in the Python environment of the process that ran the CLI. The CLI deletes the build/ folder after installation.

  • Use --dev in the edit, install, check loop, from an environment that already has the plugin’s dependencies.

  • Do not use it to produce anything you plan to share.

  • If a plugin installed with --dev fails on a third-party import, run one normal designer-install (which bundles dependencies), or install the missing packages into the environment that ran the CLI.

Install an Existing YXI with install-yxi

install-yxi installs a YXI built by the CLI or received from someone else:

 ayx_plugin_cli install-yxi --yxi-path path\to\package.yxi --install-type user

The file must exist and be readable. The command asks before overwriting an installed plugin of the same name. It rejects YXIs built with the original, pre-CLI Alteryx Python SDK.

Verify the Install

  1. Restart Designer.

  2. Find the plugin in the palette under its tool category, or search by name or search tag.

  3. Place it on a workflow, connect inputs that match its type, and run.

  4. Open the plugin’s settings to confirm the configuration panel loads. Save, close, reopen the workflow, and confirm the settings persisted.

  5. Check Designer’s message output for the plugin’s own messages and any errors.

Packaging Failures

Symptom

Likely Cause and Action

create-yxi fails during the panel build with ERR_OSSL_EVP_UNSUPPORTED.

The panel’s build tooling (webpack 4) is running on a newer Node release. Add --openssl-legacy-provider to the node options in the panel’s package.json scripts, or use an older Node release.

create-yxi seems to hang after the panel build succeeds.

Check whether build/yxi/<package>.yxi was already produced before running it again.

Node or npm version error at start.

Install Node 18 or later with a matching npm, or use --omit-ui for a backend-only build.

Plugin installed but missing from the tool palette.

Restart Designer. Confirm the install type matches where you looked, and that the plugin folder exists under the Tools directory.

Plugin loads but fails with an import or version error at runtime.

Python version mismatch, or a missing entry in backend/requirements-thirdparty.txt.

For more diagnostic steps, go to Troubleshooting and Limitations.