Skip to content

Installation

Get Xeepy up and running in under 2 minutes.

Quick Install

pip install xeepy

pipx install xeepy

poetry add xeepy

git clone https://github.com/xeepy/xeepy.git
cd xeepy
pip install -e .

Install Browser

Xeepy uses Playwright for browser automation. Install the browser:

playwright install chromium

First-time setup

This downloads a Chromium browser (~150MB). It's a one-time operation.

Verify Installation

# Check version
xeepy --version

# Run diagnostics
xeepy doctor

Expected output: 

Xeepy v1.0.0
✓ Python 3.10+
✓ Playwright installed
✓ Chromium browser ready
✓ All systems operational

Optional Dependencies

Install additional features based on your needs:

pip install "xeepy[ai]"

Includes: OpenAI, Anthropic, and Ollama integrations

pip install "xeepy[data]"

Includes: pandas, numpy, matplotlib for analytics

pip install "xeepy[notify]"

Includes: Discord, Telegram, email integrations

pip install "xeepy[all]"

Includes everything above

System Requirements

Minimum Requirements

Component Requirement
Python 3.10 or higher
RAM 512MB available
Disk 500MB for browser
OS Linux, macOS, Windows
Component Recommendation
Python 3.11+ (faster async)
RAM 2GB+ for heavy scraping
Disk SSD for database caching
Network Stable connection

Platform-Specific Notes

# Install system dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y python3-pip

# Install Xeepy
pip3 install xeepy
playwright install chromium

# Install browser dependencies
playwright install-deps chromium

Headless servers

Xeepy works perfectly on headless Linux servers. Use headless=True (default) in your scripts.

# Using Homebrew Python
brew install python@3.11

# Install Xeepy
pip3 install xeepy
playwright install chromium

Apple Silicon

Xeepy fully supports M1/M2/M3 Macs natively.

# Install Python from python.org first

# Install Xeepy
pip install xeepy
playwright install chromium

Windows Defender

You may need to allow Playwright through Windows Defender.

FROM mcr.microsoft.com/playwright/python:v1.40.0-jammy

RUN pip install xeepy[all]

# Your script
COPY script.py .
CMD ["python", "script.py"]

Or use our pre-built image:

docker pull xeepy/xeepy:latest
docker run -it xeepy/xeepy python your_script.py

Virtual Environment Setup

We recommend using a virtual environment:

# Create virtual environment
python -m venv xeepy-env

# Activate it
source xeepy-env/bin/activate  # Linux/macOS
# or
xeepy-env\Scripts\activate     # Windows

# Install Xeepy
pip install xeepy[all]
playwright install chromium

Development Installation

For contributing or modifying Xeepy:

# Clone the repository
git clone https://github.com/xeepy/xeepy.git
cd xeepy

# Create dev environment
python -m venv .venv
source .venv/bin/activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

Troubleshooting

Error: playwright not found

Make sure playwright is installed: 

pip install playwright
playwright install chromium

Error: browser closed unexpectedly

Install browser dependencies: 

# Linux only
playwright install-deps chromium

Error: Permission denied

Use --user flag or a virtual environment: 

pip install --user xeepy

Slow installation on Linux

The browser download can be slow. Use a mirror: 

PLAYWRIGHT_DOWNLOAD_HOST=https://playwright.azureedge.net playwright install chromium

Import errors after installation

Ensure you're using the correct Python: 

which python  # Should show your venv
python -c "import xeepy; print(xeepy.__version__)"

Upgrading

# Upgrade Xeepy
pip install --upgrade xeepy

# Upgrade browser (occasionally needed)
playwright install chromium

Uninstalling

# Remove Xeepy
pip uninstall xeepy

# Remove browser (optional)
rm -rf ~/.cache/ms-playwright

Next: Set up authentication →