Installation

Requirements

Requirement	Version
Python	3.9 or later
pip	any recent version
Git	optional, needed for the git plugin
bun	1.0+ (only needed to run/build this docs site)

Step 1 — Get the source

git clone https://github.com/srs-sudeep/XShell.git
cd XShell

Step 2 — Create a virtual environment (recommended)

Windows

python -m venv .venv
.venv\Scripts\activate

macOS / Linux

python -m venv .venv
source .venv/bin/activate

Step 3 — Install Python dependencies

pip install -r requirements.txt

This installs:

Package	Purpose
flask + flask-socketio	Web terminal server
prompt_toolkit	Cross-platform readline input
rich	Beautiful output (tables, panels)
Pygments	Syntax highlighting
psutil	System info plugin (optional)
pyinstaller	Standalone build tool

Step 4 — Launch

# Native terminal
python main.py

# Browser terminal
python main.py --web

Source checkout note: the web app resolves templates/ and static/ from the repository root, and project-local plugins and themes are loaded from the repository plugins/ and themes/ folders. Running python /full/path/to/main.py --web from another directory is supported.

---

Installing the docs site

The documentation site uses Docusaurus and is managed with bun.

# Move into the docs directory
cd docs-site

# Install dependencies with bun
bun install

# Start local dev server (hot-reload)
bun start

# Build static site
bun run build

# Serve the built site
bun run serve

The dev server runs at http://localhost:3000 by default.

• Download releases: github.com/srs-sudeep/XShell/releases
• Repository: github.com/srs-sudeep/XShell
• Live docs: x-shell.vercel.app

---

Troubleshooting

ModuleNotFoundError: No module named 'prompt_toolkit'

You forgot to install requirements, or your venv isn't activated.
Run pip install -r requirements.txt inside the activated venv.

Port 5000 already in use (web mode)

Pass a custom port: python main.py --web --port 8080

Windows: Unicode errors in terminal

XShell automatically falls back to ASCII symbols on cp1252 terminals.
For full Unicode support, use Windows Terminal or set:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8