Using other package managers

This guide explains how to install and set up Kamihi projects using package managers other than uv. While Kamihi's templates and documentation default to uv, you can successfully use pip with virtual environments or Poetry for dependency management.

Prerequisites⚓︎

Python 3.12 or higher installed on your system
Basic familiarity with Python package management
For Poetry: Poetry installed on your system (installation guide)

Why use alternative package managers⚓︎

While uv offers exceptional performance and modern features, you might prefer other package managers for various reasons:

Team consistency: Your team already uses pip or Poetry
Tooling integration: Existing CI/CD pipelines or IDE configurations
Familiarity: Comfort with established workflows
Corporate policies: Organization requirements for specific tools

Installation approaches⚓︎

Using pip with virtual environments⚓︎

This approach uses Python's built-in venv module with pip for dependency management.

Creating a new project⚓︎

Create and navigate to your project directory:
```
mkdir hello-world
cd hello-world
```
Create a virtual environment:
```
python -m venv .venv
```
Activate the virtual environment:
Linux/macOSWindows (Command Prompt)Windows (PowerShell)
source .venv/bin/activate
.venv\Scripts\activate.bat
.venv\Scripts\Activate.ps1
Install Kamihi:
```
pip install kamihi
```

Create project structure manually:

Since kamihi init creates a uv-based project, you'll need to adapt the structure:

# Create necessary directories
mkdir actions models
mkdir actions/start

# Create __init__.py files
touch actions/__init__.py
touch actions/start/__init__.py
touch models/__init__.py

Create essential files:

Create a requirements.txt file for dependency management:

kamihi>=1.0.0

Create a basic kamihi.yml configuration file:

---
token: YOUR_TOKEN_HERE
timezone: UTC

Create a sample action in actions/start/start.py:

from kamihi import bot
from telegram import Update
from telegram.ext import ContextTypes

@bot.action(description="Start the bot")
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Handle the /start command."""
    await update.message.reply_text("Hello! I'm your Kamihi bot.")

Running your project⚓︎

Ensure your virtual environment is activated:

The command prompt should show (.venv) prefix when activated.
Run the bot:
```
kamihi run
```

Managing dependencies⚓︎

To add new dependencies to your project:

# Install a new package
pip install package-name

# Update requirements.txt
pip freeze > requirements.txt

To install dependencies on a new machine:

# Activate virtual environment first
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate.bat  # Windows

# Install dependencies
pip install -r requirements.txt

Using Poetry⚓︎

Poetry provides a more modern approach to Python dependency management with automatic virtual environment handling.

Creating a new project⚓︎

Initialize a new Poetry project:
```
poetry new hello-world
cd hello-world
```
Add Kamihi as a dependency:
```
poetry add kamihi
```

Create project structure:

Poetry creates a different directory structure by default. Adapt it for Kamihi:

# Remove the default package directory if it exists
rm -rf hello_world/

# Create Kamihi-expected directories
mkdir actions models
mkdir actions/start

# Create __init__.py files
touch actions/__init__.py
touch actions/start/__init__.py
touch models/__init__.py

Create essential files:

Create a kamihi.yml configuration file:

---
token: YOUR_TOKEN_HERE
timezone: UTC

Create a sample action in actions/start/start.py:

from kamihi import bot
from telegram import Update
from telegram.ext import ContextTypes

@bot.action(description="Start the bot")
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Handle the /start command."""
    await update.message.reply_text("Hello! I'm your Kamihi bot.")

Running your project⚓︎

Run the bot using Poetry:
```
poetry run kamihi run
```
Alternatively, you can activate Poetry's virtual environment:
```
poetry shell
kamihi run
```

Managing dependencies⚓︎

Poetry simplifies dependency management:

# Add a new dependency
poetry add package-name

# Add a development dependency
poetry add --group dev package-name

# Update dependencies
poetry update

# Install dependencies (useful for new machines)
poetry install

Converting existing uv projects⚓︎

If you have an existing Kamihi project created with uv that you want to convert:

Converting to pip + venv⚓︎

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate.bat  # Windows

Convert dependencies:

Extract dependencies from pyproject.toml and create requirements.txt:

# If uv is still available
uv pip compile pyproject.toml -o requirements.txt

# Or manually create requirements.txt based on pyproject.toml dependencies

Install dependencies:
```
pip install -r requirements.txt
```
Remove uv-specific files (optional):
```
rm uv.lock  # If you no longer need uv
```

Converting to Poetry⚓︎

Initialize Poetry in the existing directory:
```
poetry init
```
Add dependencies from pyproject.toml:

Poetry can read the existing pyproject.toml if it follows standard format:
```
poetry install
```
Or manually add each dependency:
```
poetry add kamihi
# Add other dependencies as needed
```
Remove uv-specific files (optional):
```
rm uv.lock  # If you no longer need uv
```

Important considerations⚓︎

Virtual environment activation⚓︎

Unlike uv, which can automatically manage Python environments, pip requires manual virtual environment activation. Always ensure your virtual environment is activated before running commands.

Dependency resolution⚓︎

uv: Provides fast, deterministic dependency resolution
pip: May require manual conflict resolution for complex dependencies
Poetry: Provides deterministic resolution similar to uv but may be slower

Performance differences⚓︎

uv typically offers significantly faster installation and resolution times compared to pip and Poetry. If performance is critical, consider using uv even if your team prefers other tools for some workflows.

Docker deployment⚓︎

When deploying with Docker, you may need to adapt the Dockerfile provided by Kamihi templates. The default Dockerfile uses uv for multi-stage builds and optimized performance.

Notes⚓︎

Kamihi's core functionality remains the same regardless of the package manager used
The kamihi CLI commands work identically across all package managers
Consider your team's existing toolchain and workflows when choosing a package manager
All package managers can coexist in the same environment if needed for different projects