Installation¶

This guide covers installing kibana-py and its optional dependencies.

Requirements¶

Before installing kibana-py, ensure you have:

Python 3.11 or higher - The library requires Python 3.11+
Kibana 9.x - Compatible with Kibana version 9.x
pip - Python package installer (usually included with Python)

Basic Installation¶

Install kibana-py using pip:

pip install kibana-py

This installs the core library with synchronous client support and all required dependencies:

elastic-transport (>=9.1.0, <10) - HTTP transport layer
python-dateutil - Date/time utilities
typing-extensions - Extended type hints

Optional Dependencies¶

kibana-py provides several optional dependency groups for additional functionality.

Async Support¶

For asynchronous client support using AsyncKibana:

pip install kibana-py[async]

This installs:

aiohttp (>=3, <4) - Async HTTP client library

Use this if you need to make concurrent requests or integrate with async Python applications.

High-Performance JSON¶

For faster JSON serialization and deserialization:

pip install kibana-py[orjson]

This installs:

orjson (>=3) - High-performance JSON library

The library automatically uses orjson when available, providing significant performance improvements for large payloads.

Observability¶

For OpenTelemetry distributed tracing support:

pip install kibana-py[observability]

This installs:

opentelemetry-api (>=1.20.0) - OpenTelemetry API
opentelemetry-sdk (>=1.20.0) - OpenTelemetry SDK
opentelemetry-exporter-otlp-proto-grpc (>=1.20.0) - OTLP gRPC exporter
opentelemetry-exporter-otlp-proto-http (>=1.20.0) - OTLP HTTP/protobuf exporter
opentelemetry-instrumentation (>=0.40b0) - Base instrumentation API used by KibanaInstrumentor

Use this for production monitoring and distributed tracing. See the OpenTelemetry Observability guide for configuration details.

All Optional Dependencies¶

To install all optional dependencies at once:

pip install kibana-py[async,orjson,observability]

Or use the all extra:

pip install kibana-py[all]

Development Installation¶

If you’re contributing to kibana-py or want to run tests:

# Clone the repository
git clone https://github.com/pedro-angel/kibana-py.git
cd kibana-py

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

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

The dev extra includes all optional dependencies plus testing and development tools:

pytest, pytest-cov, pytest-mock, pytest-asyncio
black, isort, ruff
mypy, pyright
nox

Verifying Installation¶

After installation, verify that kibana-py is installed correctly:

import kibana
print(kibana.__version__)

You can also check which optional dependencies are available:

from kibana import Kibana

# Check if async support is available
try:
    from kibana import AsyncKibana
    print("✓ Async support available")
except ImportError:
    print("✗ Async support not available (install with: pip install kibana-py[async])")

# Check if orjson is available
try:
    import orjson
    print("✓ orjson available")
except ImportError:
    print("✗ orjson not available (install with: pip install kibana-py[orjson])")

# Check if OpenTelemetry is available
try:
    from opentelemetry import trace
    print("✓ OpenTelemetry available")
except ImportError:
    print("✗ OpenTelemetry not available (install with: pip install kibana-py[observability])")

Troubleshooting¶

Python Version Issues¶

If you encounter errors about Python version:

# Check your Python version
python --version

# If you have multiple Python versions, use python3.11+ explicitly
python3.11 -m pip install kibana-py

SSL Certificate Errors¶

If you encounter SSL certificate verification errors:

from kibana import Kibana

# Disable certificate verification (not recommended for production)
client = Kibana(
    "https://localhost:5601",
    verify_certs=False
)

# Or provide a custom CA certificate
client = Kibana(
    "https://localhost:5601",
    ca_certs="/path/to/ca.crt"
)

See Common Issues for more solutions.

Connection Issues¶

If you can’t connect to Kibana:

Verify Kibana is running: Check that Kibana is accessible at the URL you’re using
Check authentication: Ensure your credentials are correct
Verify network access: Ensure there are no firewalls blocking the connection
Check Kibana version: Ensure you’re using Kibana 9.x

from kibana import Kibana

# Test connection
try:
    client = Kibana("http://localhost:5601")
    status = client.status.get_status()
    print(f"✓ Connected to Kibana: {status.body['status']['overall']['level']}")
except Exception as e:
    print(f"✗ Connection failed: {e}")
finally:
    client.close()

Import Errors¶

If you encounter import errors:

# Ensure kibana-py is installed in the correct environment
pip list | grep kibana

# Reinstall if necessary
pip uninstall kibana-py
pip install kibana-py

Upgrading¶

To upgrade to the latest version:

pip install --upgrade kibana-py

To upgrade with all optional dependencies:

pip install --upgrade kibana-py[all]

Uninstalling¶

To remove kibana-py:

pip uninstall kibana-py

Next Steps¶

Now that you have kibana-py installed, check out the Quick Start guide to start using the library.

For detailed usage information, see the User Guide.