Installation¶

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

Requirements¶

Before installing kibana-py, ensure you have:

Python 3.10 or higher - The library requires Python 3.10+
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

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.10+ explicitly
python3.10 -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.