Skip to main content

​
System Requirements

Tinbox requires Python 3.12 or higher to run properly.
Before installing Tinbox, ensure your system meets these requirements:
  • Python: 3.12 or 3.13
  • Operating System: macOS, Linux, or Windows
  • System Tools: Poppler (required for PDF processing)

​
Python Installation

# Using Homebrew
brew install [email protected]

# Verify installation
python3 --version

​
Installing Tinbox

Tinbox is installed from source. First, clone the repository:
git clone https://github.com/strickvl/tinbox
cd tinbox

​
System Dependencies

​
Poppler (Required for PDF Processing)

PDF translation will not work without Poppler installed on your system.
Poppler is required to convert PDF pages to images for vision-capable models: 
brew install poppler

​
API Keys Setup

Tinbox requires API keys to access LLM providers. Set up the keys for your preferred provider: 
export OPENAI_API_KEY="sk-your-openai-api-key-here"
To make API keys permanent, add the export commands to your shell profile:
  • Bash: ~/.bashrc or ~/.bash_profile
  • Zsh: ~/.zshrc
  • Fish: ~/.config/fish/config.fish

​
Getting API Keys

OpenAI

Get your OpenAI API key for GPT-4o and GPT-5 models

Anthropic

Get your Anthropic API key for Claude models

Google AI

Get your Google API key for Gemini models

​
Local Models with Ollama

Want to use local models without API costs? Install Ollama for free local translation.
1

Install Ollama

Download and install from ollama.ai
# macOS/Linux
curl -fsSL https://ollama.ai/install.sh | sh
2

Pull a Model

# Download a model (e.g., Llama 3.1)
ollama pull llama3.1:8b
3

Start Ollama Server

ollama serve
Keep this running in a separate terminal.
4

Use with Tinbox

tinbox translate --to de --model ollama:llama3.1:8b document.txt

​
Verify Installation

Run the diagnostic tool to check your setup: 
tinbox doctor
This command checks:
  • ✅ Python version (3.12+)
  • ✅ Required system tools (poppler)
  • ✅ Optional dependencies (pdf2image, python-docx)
  • ✅ API key configuration

​
Example Output

🔍 Checking Tinbox Setup...

✅ Python version: 3.12.0
✅ Poppler installed: /usr/local/bin/pdftoimage
✅ pdf2image available
✅ python-docx available
✅ OpenAI API key configured
⚠️  Anthropic API key not found

Setup complete! You're ready to translate documents.

​
Development Installation

If you want to contribute to Tinbox or modify the source code:
# Clone the repository
git clone <repository-url>
cd tinbox

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

# Install with development dependencies
pip install -e ".[dev]"
This includes additional tools:
  • pytest for testing
  • black for code formatting
  • mypy for type checking
  • ruff for linting
  • pytest-cov for coverage reports

​
Troubleshooting

Problem: Error when translating PDFsSolutions:
  1. Install poppler: brew install poppler (macOS) or sudo apt-get install poppler-utils (Linux)
  2. Use a vision-capable model: GPT-4o, Claude Sonnet, or Gemini Pro Vision
  3. Install PDF extras: pip install tinbox[pdf]
Problem: Missing PDF processing librarySolution: Install PDF support:
pip install tinbox[pdf]
# or
pip install -e ".[all]"
Problem: “API key not configured” errorSolution: Set your API key as an environment variable:
export OPENAI_API_KEY="your-key-here"
Make it permanent by adding to ~/.bashrc or ~/.zshrc
Problem: Large documents timeout or failSolutions:
  1. Use smaller chunks: --context-size 1500
  2. Enable checkpointing: --checkpoint-dir ./checkpoints
  3. Use page-by-page for PDFs: --algorithm page

​
Next Steps

Quick Start

Jump into translating your first document

Introduction

Learn more about Tinbox features and capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us