Skip to content

Installation

This guide covers how to install PyCharter and its optional dependencies.

Requirements

  • Python 3.11+ (3.12 or 3.13 recommended)
  • pip or uv package manager

Quick Install

Core Library

The core library includes validation, contracts, and Pydantic generation:

pip install pycharter

With ETL Support

For ETL pipelines with cloud storage support:

pip install pycharter[etl]

This adds:

  • boto3 - AWS S3 support
  • google-cloud-storage - Google Cloud Storage support
  • azure-storage-blob - Azure Blob Storage support
  • sshtunnel - SSH tunnel for secure database connections
  • openpyxl - Excel file support
  • lxml - XML file support

With API Server

For the REST API server:

pip install pycharter[api]

This adds:

  • fastapi - Web framework
  • uvicorn - ASGI server
  • pydantic-settings - Settings management

With Web UI

For the interactive web interface:

pip install pycharter[ui]

With Streaming Support

For real-time streaming extractors (WebSocket, FileWatcher):

pip install pycharter[streaming]

This adds:

  • websockets - WebSocket extractor
  • watchfiles - Efficient file system monitoring

With Messaging Support

For message queue extractors (Kafka, RabbitMQ):

pip install pycharter[messaging]   # Kafka + RabbitMQ
pip install pycharter[kafka]       # Kafka only
pip install pycharter[rabbitmq]    # RabbitMQ only

This adds:

  • aiokafka - Apache Kafka consumer
  • aio-pika - RabbitMQ consumer

Note

SQS support uses boto3, which is included in the [etl] extra.

Full Installation

Install everything:

pip install pycharter[all]

Or pick specific extras:

pip install pycharter[api,ui,etl,streaming,messaging]

Development Installation

For contributing to PyCharter:

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

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev,api,ui,etl]"

# Run tests to verify installation
pytest

Database Setup

PyCharter supports multiple database backends for the metadata store:

SQLite (Default - No Setup Required)

from pycharter import SQLiteMetadataStore

store = SQLiteMetadataStore("pycharter.db")
store.connect()

PostgreSQL

  1. Install PostgreSQL and create a database:
createdb pycharter
  1. Install the PostgreSQL driver:
pip install psycopg2-binary
  1. Connect:
from pycharter import PostgresMetadataStore

store = PostgresMetadataStore("postgresql://user:pass@localhost/pycharter")
store.connect()

MongoDB

  1. Install MongoDB and start the server

  2. Install the MongoDB driver:

pip install pymongo
  1. Connect:
from pycharter import MongoDBMetadataStore

store = MongoDBMetadataStore("mongodb://localhost:27017/pycharter")
store.connect()

Redis

  1. Install Redis and start the server

  2. Install the Redis driver:

pip install redis
  1. Connect:
from pycharter import RedisMetadataStore

store = RedisMetadataStore("redis://localhost:6379/0")
store.connect()

Verify Installation

Run the following to verify your installation:

import pycharter
print(f"PyCharter version: {pycharter.__version__}")

# Test basic functionality
from pycharter import from_dict, validate

schema = {
    "type": "object",
    "version": "1.0.0",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "required": ["name"]
}

Model = from_dict(schema, "TestModel")
result = validate(Model, {"name": "Test", "age": 25})
print(f"Validation passed: {result.is_valid}")

CLI Verification

After installation, the pycharter CLI should be available:

# Check version
pycharter --version

# Start API server (if [api] installed)
pycharter api

# Start UI development server (if [ui] installed)
pycharter ui serve

Troubleshooting

Import Errors

If you get import errors, ensure you have the correct optional dependencies:

# Check what's installed
pip show pycharter

# Reinstall with extras
pip install --upgrade pycharter[api,ui,etl]

Database Connection Issues

For PostgreSQL connection issues:

# Test connection
psql postgresql://user:pass@localhost/pycharter -c "SELECT 1"

# Check if psycopg2 is installed
python -c "import psycopg2; print('OK')"

Permission Errors

On macOS/Linux, you may need to use pip install --user or a virtual environment.

Next Steps