This guide helps you resolve common installation and setup issues with AskUI.

​
Installation Errors

​
Windows Long Path Support

Some Windows systems have issues with long file paths during installation. Solution:
  1. Open askui-shell as Administrator
  2. Run: AskUI-EnableLongPath
  3. Restart your system
  4. Try the installation again
To verify long path support: 
AskUI-TestLongPathSupport

​
IDE Integration

​
VSCode Custom Terminal Setup

To use askui-shell as your default terminal in VSCode:
  1. Open VS Code Settings (Ctrl+,)
  2. Click “Open Settings (JSON)” icon
  3. Add this configuration:
{
    "terminal.integrated.profiles.windows": {
        "askui-shell": {
            "path": [
                "${env:USERPROFILE}\\AppData\\Local\\Programs\\askui\\askui-shell\\AskUI-Shell.exe"
            ],
            "args": ["-ExecutionPolicy", "Bypass", "-NoExit", "-NoLogo"],
            "icon": "terminal-powershell"
        }
    },
    "terminal.integrated.defaultProfile.windows": "askui-shell"
}
For macOS: 
    "terminal.integrated.profiles.osx": {
        "askui-shell": {
            "path": "/bin/zsh",
            "args": [
                "-l",
                "-c",
                "$ASKUI_INSTALLATION_DIRECTORY/Tools/askui-shell"
            ],
            "icon": "robot",
            "overrideName": true,
            "color": "terminal.ansiMagenta"
        }
    },
    "terminal.integrated.defaultProfile.osx": "askui-shell"
}
For Linux: 
{
    "terminal.integrated.profiles.linux": {
        "askui-shell": {
            "path": "/bin/bash",
            "args": [
                "-l",
                "-c",
                "$ASKUI_INSTALLATION_DIRECTORY/Tools/askui-shell"
            ],
            "icon": "robot",
            "overrideName": true,
            "color": "terminal.ansiMagenta"
        }
    },
    "terminal.integrated.defaultProfile.linux": "askui-shell"
}

​
PyCharm Terminal Setup

  1. Go to Settings > Tools > Terminal
  2. Set Shell path to:
    • Windows: %USERPROFILE%\AppData\Local\Programs\askui\askui-shell\AskUI-Shell.exe
    • macOS: $ASKUI_INSTALLATION_DIRECTORY/Tools/askui-shell
    • linux: $ASKUI_INSTALLATION_DIRECTORY/Tools/askui-shell
  3. Apply and restart PyCharm

​
Environment Configuration

​
Using .env Files Instead of askui-shell

If you prefer not to use askui-shell, you can configure credentials via environment files:
  1. Install python-dotenv:
pip install python-dotenv
  1. Create .env file in your project root:
ASKUI_WORKSPACE_ID=<your workspace id>
ASKUI_TOKEN=<your access token>
  1. Load in your Python script:
from dotenv import load_dotenv
import os

load_dotenv()

from askui import VisionAgent

# Credentials are loaded from .env automatically
with VisionAgent() as agent:
    pass  # Your agent code here
Need tokens? See Create Access Tokens

​
Python Environment Issues

​
Virtual Environment Setup

Always use a virtual environment to avoid conflicts: 
# Create virtual environment
python -m venv askui_env

# Activate (Windows)
askui_env\Scripts\activate

# Activate (macOS/Linux)
source askui_env/bin/activate

# Install AskUI
pip install askui

​
Managing Multiple Python Versions

Use askui-shell to manage Python environments: 
# Create new environment
AskUI-NewPythonEnvironment -Name "myproject"

# List environments
AskUI-ShowPythonEnvironments

# Activate environment
AskUI-EnablePythonEnvironment -Name "myproject"

​
Network Connectivity Check

After installation, verify everything works:
  1. Open askui-shell
  2. Run: AskUI-TestConnection
  3. Check versions: AskUI-ShowVersions
If tests fail, see Network and Connectivity guide.

​
Common Installation Locations

  • Windows: %USERPROFILE%\AppData\Local\Programs\askui
  • macOS: /Applications/AskUI or /usr/local/bin/askui-shell
  • Linux: /opt/askui or /usr/local/bin/askui-shell

​
Next Steps