Skip to content

Installation

Prerequisites

Before starting, ensure you have:

  • Python 3.14 or higher

Check your version with:

python --version

If needed, download Python 3.14+.

  • uv (recommended package manager)

uv is a fast Python package installer and resolver. Install it via the official guide.

Tip: ArchiPy recommends uv — it is significantly faster than pip and provides better dependency resolution.

Install ArchiPy

Install the core library:

uv add archipy

pip install archipy

With optional extras (install only what you need):

uv add "archipy[postgres,mysql,sqlalchemy,starrocks,redis,keycloak,minio,kafka]"

pip install "archipy[postgres,mysql,sqlalchemy,starrocks,redis,keycloak,minio,kafka]"

Optional Dependencies

ArchiPy supports modular features through optional extras — install only what you need:

Category Extra Description
Database archipy[postgres] PostgreSQL adapter with SQLAlchemy integration
Database archipy[mysql] MySQL adapter with SQLAlchemy integration
Database archipy[mysql-async] MySQL async adapter (asyncmy2)
Database archipy[aiosqlite] SQLite async adapter with SQLAlchemy integration
Database archipy[starrocks] StarRocks adapter with SQLAlchemy integration
Database archipy[starrocks-async] StarRocks async adapter
Database archipy[sqlalchemy] SQLAlchemy core integration
Database archipy[sqlalchemy-async] SQLAlchemy async integration
Database archipy[elasticsearch] Elasticsearch integration
Database archipy[elasticsearch-async] Elasticsearch async integration
Database archipy[scylladb] ScyllaDB integration
Service archipy[redis] Redis caching and key-value storage
Service archipy[keycloak] Authentication and authorization services
Service archipy[minio] S3-compatible object storage
Service archipy[kafka] Message streaming and event processing
Service archipy[temporalio] Temporal workflow engine
Service archipy[parsian-ipg] Payment gateway (Parsian)
Service archipy[saman-ipg] Payment gateway (Saman)
Web archipy[fastapi] FastAPI integration with middleware and utilities
Web archipy[grpc] gRPC integration with interceptors
Observability archipy[otel] OpenTelemetry SDK, OTLP, httpx/requests, threading, system metrics
Observability archipy[otel-fastapi] FastAPI auto-instrumentation
Observability archipy[otel-grpc] gRPC server/client contrib interceptors
Observability archipy[otel-sqlalchemy] SQLAlchemy instrumentation
Observability archipy[otel-redis] Redis instrumentation
Observability archipy[otel-elasticsearch] Elasticsearch instrumentation
Observability archipy[otel-kafka] Confluent Kafka instrumentation
Observability archipy[otel-scylladb] Cassandra/ScyllaDB instrumentation
Observability archipy[otel-minio] Botocore (MinIO/S3) instrumentation
Utilities archipy[jwt] JSON Web Token utilities
Utilities archipy[scheduler] Task scheduling utilities
Utilities archipy[cache] TTL and async caching utilities
Utilities archipy[dependency-injection] Dependency injector support
Testing archipy[fakeredis] In-memory Redis mock for testing
Testing archipy[testcontainers] Testcontainers integration
Testing archipy[behave] BDD testing framework

Note: Enable observability with OTEL__IS_ENABLED=true and install the matching otel-* extras for each stack you use. See Observability.

Note: ArchiPy’s HTTP clients (for example payment IPG adapters) use httpx2. The otel extra instruments httpx and requests, not httpx2 — outbound httpx2 calls are a known auto-instrumentation gap.

Troubleshooting

If issues arise, verify:

  1. Python version is 3.14+
  2. uv is updated (uv self update)
  3. Build tools are available (UV handles this automatically)
  4. Database-specific dependencies are installed if using database adapters

Warning: ArchiPy uses X | Y union syntax, lowercase generics (list[str]), and other modern features that require Python 3.14 or later. Using an older Python will result in SyntaxError at import time.

Tip: For the best development experience, use an IDE that supports Python type hints, such as PyCharm or VS Code with the Python extension. The project uses modern Python type hints and benefits from IDE support for type checking and autocompletion.

See Also

  • Get Started — overview of ArchiPy and a quick example
  • Concepts — Clean Architecture layers and design philosophy
  • Tutorials — complete guides for every adapter and helper