Installation - PyCharter
Description: Data Contract Management, ETL Pipelines, and Quality Assurance for Python

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

- Quick Start Guide - Run your first pipeline
- Core Concepts - Understand PyCharter's architecture
- ETL Tutorial - Build data pipelines