> ## Documentation Index
> Fetch the complete documentation index at: https://docs.askui.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation and Setup Issues

> Solutions for common installation and setup problems

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:

```powershell theme={null}
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:

```json theme={null}
{
    "terminal.integrated.profiles.windows": {
        "askui-shell": {
            "path": [
                "${env:ASKUI_INSTALLATION_DIRECTORY}\\Tools\\askui-shell.cmd"
            ],
            "args": ["-ExecutionPolicy", "Bypass", "-NoExit", "-NoLogo"],
            "icon": "terminal-powershell"
        }
    },
    "terminal.integrated.defaultProfile.windows": "askui-shell"
}
```

For macOS:

```json theme={null}
    "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:

```json theme={null}
{
    "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: `%ASKUI_INSTALLATION_DIRECTORY%\\Tools\\askui-shell.cmd`
   * 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:

```bash theme={null}
pip install python-dotenv
```

2. Create `.env` file in your project root:

```env theme={null}
ASKUI_WORKSPACE_ID=<your workspace id>
ASKUI_TOKEN=<your access token>
```

3. Load in your Python script:

```python theme={null}
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
```

<Note>
  Need tokens? See [Create Access Tokens](/02-how-to-guides/01-account-management/04-tokens)
</Note>

## Python Environment Issues

### Virtual Environment Setup

Always use a virtual environment to avoid conflicts:

```bash theme={null}
# 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:

```powershell theme={null}
# 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](/02-how-to-guides/04-troubleshooting/02-network-and-connectivity) guide.

## Common Installation Locations

* **Windows**: `%APPDATA%\askui GmbH\AskUI Suite\.askui-suite`
* **macOS**: `/Applications/.askui-suite`
* **Linux**: `/opt/askui` or `/usr/local/bin/askui-shell`

## Next Steps

* Installation successful? Start with our [Quickstart Guide](/01-tutorials/01-quickstart)
* Having network issues? See [Network and Connectivity](/02-how-to-guides/04-troubleshooting/02-network-and-connectivity)
* Need help? [Report an issue](/02-how-to-guides/04-troubleshooting/06-reporting-bugs-and-getting-help)