Installation Guide

This guide covers different ways to install PyPositron and its dependencies.

System Requirements

• Python: 3.9 or higher
• Operating Systems: Windows, macOS, Linux
• Dependencies: pywebview, pathlib2, pyqt5

Installation Methods

Method 1: Install from PyPI (Recommended)

The easiest way to install PyPositron:

pip install py-positron

Method 2: Install with Virtual Environment

For better project isolation:

# Create a virtual environment
python -m venv positron-env

# Activate the virtual environment
# On Windows:
positron-env\Scripts\activate
# On macOS/Linux:
source positron-env/bin/activate

# Install PyPositron
pip install py-positron

Method 3: Development Installation

If you want to contribute or modify PyPositron:

# Clone the repository
git clone https://github.com/itzmetanjim/py-positron.git
cd py-positron

# Install in editable mode
pip install -e .

Verify Installation

After installation, verify that PyPositron is working correctly:

# Check if the positron command is available
positron help

# Check the installed version
pip show py-positron

You should see the help message with available commands.

Dependencies

PyPositron automatically installs the following dependencies:

• pywebview: For creating native webview windows
• pathlib2: For cross-platform path handling
• pyqt5: For GUI framework support

Platform-Specific Notes

Windows

• No additional setup required
• PyQt5 will be automatically installed
• Windows Defender might show a warning for the first run

macOS

• You may need to install Xcode Command Line Tools:

  xcode-select --install
  

• For virtual environments on macOS, you might need to create them manually. See the manual venv creation guide

Linux

• You may need to install additional system packages:

  # Ubuntu/Debian
  sudo apt-get install python3-dev python3-pip python3-venv
  
  # Red Hat/Fedora
  sudo dnf install python3-devel python3-pip python3-venv
  

Troubleshooting Installation

Common Issues

1. Permission Errors

   # Use --user flag to install for current user only
   pip install --user py-positron
   

2. Python Version Issues

   # Make sure you're using Python 3.9+
   python --version
   # Or try with python3
   python3 --version
   

3. Module Not Found Error

   # Reinstall the package
   pip uninstall py-positron
   pip install py-positron
   

4. Virtual Environment Issues

   # Make sure virtual environment is activated
   # Check which Python is being used
   which python
   which pip
   

Getting Help

If you encounter installation issues:

1. Check the Troubleshooting Guide
2. Search existing GitHub Issues
3. Create a new issue with:
   • Your operating system
   • Python version
   • Complete error message
   • Installation command used

Updating PyPositron

To update to the latest version:

pip install --upgrade py-positron

To check for available updates:

pip list --outdated | grep py-positron