Installation

Complete installation instructions for Positron framework.

Prerequisites

Before installing Positron, ensure you have:

• Python 3.8+ (3.11+ recommended)
• Node.js 16+ (18+ LTS recommended)
• npm or yarn package manager
• Tkinter (usually included with Python)

Check Prerequisites

# Check Python version
python --version  # Should be 3.8 or higher

# Check Node.js version
node --version    # Should be 16 or higher

# Check npm
npm --version

# Test Tkinter installation
python -c "import tkinter; print('Tkinter OK')"

Installing Tkinter (if needed)

sudo apt-get install python3-tk

sudo dnf install python3-tkinter

sudo pacman -S tk

Installation Methods

Method 1: CLI (Recommended)

The easiest way to start is using the CLI, which sets up Python, Node.js dependencies, and a template for you.

npm create positron-app@latest
# or
npx create-positron-app@latest

This will create a new directory with a ready-to-run Positron app.

Method 2: Manual Installation

If you prefer to install manually or want to contribute to the core framework:

Step 1: Clone Repository

git clone https://github.com/tomlin7/positron.git
cd positron

Step 2: Install Python Dependencies

pip install -r requirements.txt

pip install pywebview

pip install -e .

Step 3: Verify Installation

python -c "from positron import App, BrowserWindow; from positron.ipc import ipc_main; print('✓ Positron installed successfully!')"

Expected output:

✓ Positron installed successfully!

Running the Example App

Step 1: Navigate to Example

cd examples/react-app

Step 2: Install Node.js Dependencies

npm install

This installs:

• React and ReactDOM
• Vite and its plugins
• Development dependencies

Step 3: Run the App

python main.py

You should see:

1. Dev server starting
2. Window opening with React app
3. Beautiful gradient UI

Project Structure After Installation

positron/
├── positron/           # Installed Positron framework
├── examples/
│   └── react-app/
│       ├── node_modules/   # Created by npm install
│       └── ...

└── ...

Troubleshooting

Pywebview not found

Error:

ImportError: No module named 'webview'

Solution:

pip install pywebview

WebView2 runtime missing (Windows only)

Symptoms:

• App won't start on Windows
• Error about WebView2

Solution: WebView2 is usually pre-installed on Windows 10/11. If not, download it:

• https://developer.microsoft.com/microsoft-edge/webview2/

React app not loading

Symptoms:

• Blank page in window
• Console errors

Solution:

1. Make sure dev server is running: npm run dev
2. Check port 5173 is not blocked
3. Try loading built version: npm run build then win.load_file('dist/index.html')

Linux dependencies missing

Error on Linux:

ImportError: gi or webkit2gtk not found

Solution:

sudo apt-get install python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-webkit2-4.0

npm command not found

Error:

npm: command not found

Solution: Install Node.js from https://nodejs.org/

Dev server won't start

Error:

Error starting dev server

Solutions:

1. Make sure you ran npm install in the example directory
2. Check if port 5173 is available
3. Try a different port in vite.config.js

Window shows but is blank

Possible causes:

1. Dev server didn't start properly
2. React build errors
3. Port mismatch

Debug:

# Check console for errors
# Dev server output shows in terminal

# Test with simple HTML
python -c "
from positron import App, BrowserWindow
app = App()
def test():
    win = BrowserWindow()
    win.load_html('<h1>Test</h1>')
app.when_ready(test)
app.run()
"

Python path issues

If you get import errors when running examples:

cd /path/to/positron
pip install -e .

import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.parent.parent))

Virtual Environment (Recommended)

Use a virtual environment to avoid conflicts:

# Create virtual environment
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

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

# Install Positron
pip install -r requirements.txt

# Later: Deactivate
deactivate

Platform-Specific Notes

Windows

• Use PowerShell or Command Prompt
• Paths use backslashes: C:\Users\...
• WebView2 fully supported on Windows 10/11

macOS

• Both Intel and Apple Silicon supported
• Use Terminal or iTerm2
• May need to install Python from python.org (not system Python)

Linux

• Tkinter might need separate installation
• GTK WebKit available for Linux
• Use your distribution's package manager for dependencies

Minimum Versions

Platform Support

Positron works on all platforms with webview support:

• ✅ Windows 10/11 - Uses Microsoft Edge WebView2
• ✅ macOS 10.14+ - Uses system WebKit
• ✅ Linux - Uses GTK WebKit (Ubuntu, Fedora, Arch, etc.)

Platform-Specific Requirements

Windows:

• WebView2 Runtime (usually pre-installed)

macOS:

• No additional requirements (WebKit is built-in)

Linux:

• GTK 3 and WebKit2GTK packages

Updating

To update Positron and dependencies:

# Update Positron (pull latest changes)
cd /path/to/positron
git pull

# Update Python dependencies
pip install -r requirements.txt --upgrade

# Update Node.js dependencies (in example app)
cd examples/react-app
npm update

Uninstalling

To uninstall Positron:

# Uninstall Python packages
pip uninstall pywebview

# Remove repository
cd ..
rm -rf positron

Getting Help

If you encounter issues:

1. Check Dependencies for version requirements
2. Search GitHub Issues
3. Create a new issue with:
   • Your OS and Python version
   • Full error message
   • Steps to reproduce

Success!

If you see the example React app running in a native window, you've successfully installed Positron! 🎉

Now you're ready to build cross-platform desktop apps with Python and React.