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 | |
You are iterating locally and want the plugin in Designer now. | |
You already have a | |
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 userFor details on CLI command flags, go to Command Reference.
Before You Build
Confirm the target Designer release and set
backend_language_settings.python_versionto its embedded Python (go to Set Up Environment). Rungenerate-config-filesafter changing it.Run
ayx_plugin_cli test.If any plugin has a configuration panel, confirm Node and npm are installed. Packaging builds the panel first.
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 |
|---|---|
| Installs to |
| Installs to |
| Builds without configuration panels. |
| 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
--devin 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
--devfails on a third-party import, run one normaldesigner-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 userThe 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
Restart Designer.
Find the plugin in the palette under its tool category, or search by name or search tag.
Place it on a workflow, connect inputs that match its type, and run.
Open the plugin’s settings to confirm the configuration panel loads. Save, close, reopen the workflow, and confirm the settings persisted.
Check Designer’s message output for the plugin’s own messages and any errors.
Packaging Failures
Symptom | Likely Cause and Action |
|---|---|
| The panel’s build tooling (webpack 4) is running on a newer Node release. Add |
| Check whether |
Node or npm version error at start. | Install Node 18 or later with a matching npm, or use |
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 |
For more diagnostic steps, go to Troubleshooting and Limitations.