Welcome to the Alteryx Knowledge Base

This guide provides step-by-step instructions for upgrading existing Alteryx V2 SDK tools to Python 3.13 and configuring your development environment. Python 3.13 support requires Alteryx Python SDK version 2.5.2 or later for compatibility with Designer 2026.1 and later.

Upgrade existing Alteryx V2 SDK tools to Python 3.13 to ensure compatibility with Designer 2026.1 and later.

Use this when:

• Migrating tools built with earlier Python versions (pre-3.13)
• Aligning with the latest Alteryx SDK standards
• Resolving compatibility issues with newer Designer versions

Done, it looks like:

• Tool builds successfully using Python 3.13
• Tool installs and runs in Designer 2026.1+ without errors
• Dependencies are updated and managed using uv and nvm

Constraints:

• Requires ayx_python_sdk version 2.5.2 or later
• Node.js setup is required for tools with UI components
• Designer must support Python 3.13

Applies to:

• Alteryx Designer 2026.1+
• Alteryx Python SDK (V2)
• ayx_python_sdk 2.5.2+
• ayx_plugin_cli 1.3.2+
• Python 3.13

• Access to SDK tool project directory
• uv installed for Python environment management (Installing uv)
• nvm installed if tool includes UI (Releases)
• Permissions to install dependencies
• Existing V2 SDK tool

1. Set up development environment
   Run:
• uv python install 3.13
• uv venv --python 3.13 --seed
• .venv\Scripts\activate
  
  
2. Install dependencies
• uv pip install -r requirements.txt
• or uv sync
  
  
3. Configure Node (if applicable)
• nvm install 14
• nvm use 14
  
  
4. Upgrade SDK and CLI
• pip install --upgrade ayx_plugin_cli==1.3.2 ayx_python_sdk==2.5.2

               Common issue: Dependency conflicts

• When this occurs: During dependency installation or upgrade
• Error example: Cannot install X and Y because these package versions have conflicting dependencies
• Fix: Pin specific versions in requirements-thirdparty.txt and rebuild the environment
  
  
4. Update requirements
• Set ayx_python_sdk==2.5.2 in requirements-thirdparty.txt
  
  
5. Clean rebuild
• Delete .venv, .ayx_cli.cache, and build folders
• Recreate the environment

Common issue: ModuleNotFoundError or deadlock

• When this occurs: During ayx_plugin_cli create-yxi or designer-install
• Symptoms: Errors such as Failed to read port assignment...deadlock detected
• Cause: Missing dependency or incorrect import name
• Fix: Ensure all dependencies are correctly listed in requirements-thirdparty.txt
  
  
6. Reinstall tool
• ayx_plugin_cli designer-install --dev --install-type user
• or ayx_plugin_cli create-yxi

Common issue: Node build errors (UI tools only)

• When this occurs: During YXI creation or frontend build
• Symptoms: Build fails or UI assets are not generated
• Fix:
• npm install
• npm run build
• Verify Node version with node -v
• Run nvm use 14 if needed
  
  
7. Test
• Validate the tool runs in Designer 2026.1+

Common issues:

• SDK version incompatibility
• When this occurs: When running the tool in Designer
• Error example: TypeError or ImportError involving ayx_python_sdk
• Fix: Run pip show ayx_python_sdk and ensure version 2.5.2 or later
  
  
• Designer Python version error
• Error example: Version 3.13 was not found in our alteryx distribution
• Cause: Older Designer version
• Fix: Upgrade to Designer 2026.1 or later