Quick Start

System requirements

Before installing, ensure your system meets these requirements:

Python 3.10 or higher
Linux, MacOS, or Windows

Installation

It is recommended that you install Pixeltable in a virtual environment.

venv
uv
conda

Create virtual environment

python -m venv .venv

Activate environment

source .venv/bin/activate

.venv\Scripts\activate

Install Pixeltable

pip install pixeltable

Install uv

Install uv from the Installing uv guide.

Create environment

uv venv --python 3.12

Activate environment

source .venv/bin/activate

.venv\Scripts\activate

Install Pixeltable

uv pip install pixeltable

Install Miniconda

Download and install from the Miniconda Installation guide.

Create and activate environment

conda create --name pxt python=3.12
conda activate pxt

Install Pixeltable

pip install pixeltable

Getting help

Join our Discord Community
Report issues on GitHub
Contact [email protected]

Build an image analysis app

This guide will help you spin up a functioning AI workload in 5 minutes.

Install Required Packages

Pixeltable requires only a minimal set of Python packages by default. To use AI models, you’ll need to install additional dependencies.

pip install torch transformers openai

Create a Table

import pixeltable as pxt

# Create a namespace and table
pxt.create_dir('quickstart', if_exists='replace_force')
t = pxt.create_table('quickstart/images', {'image': pxt.Image})

Tables are persistent: your data survives restarts and can be queried anytime.

Add AI Object Detection

from pixeltable.functions import huggingface

# Add DETR object detection as a computed column
t.add_computed_column(
    detections=huggingface.detr_for_object_detection(
        t.image,
        model_id='facebook/detr-resnet-50'
    )
)

# Extract labels from detections
t.add_computed_column(labels=t.detections.label_text)

Computed columns run automatically whenever new data is inserted.

Insert Data

# Insert a few images
t.insert([
  {'image': 'https://raw.githubusercontent.com/pixeltable/pixeltable/release/docs/resources/images/000000000001.jpg'},
  {'image': 'https://raw.githubusercontent.com/pixeltable/pixeltable/release/docs/resources/images/000000000025.jpg'}
])

You can insert images from URLs and/or local paths in any combination.

Query Results

# Query results
t.select(t.image, t.labels).collect()

Expected output:

image	labels
[Image]	[car, parking meter, truck, car, car, truck]
[Image]	[giraffe, giraffe]

(Optional) Add LLM Vision

You’ll need an OpenAI API key to use this step. If you don’t have one, you can safely skip this step.

import os
from pixeltable.functions import openai

# Set your API key
os.environ['OPENAI_API_KEY'] = 'your-key-here'

messages = [
    {
        'role': 'user',
        'content': [
            {'type': 'text', 'text': 'Describe this image in one sentence.'},
            {'type': 'image_url', 'image_url': t.image},
        ],
    }
]
t.add_computed_column(
    response=openai.chat_completions(messages, model='gpt-4o-mini')
)

t.select(t.image, t.labels, t.response.choices[0].message.content).collect()

# See the full text of the response in row 0
t.select(t.response.choices[0].message.content).collect()[0]

Pixeltable orchestrates LLM calls for optimized throughput, handling rate limiting, retries, and caching automatically.

Insert More Data

t.insert([
  {'image': 'https://raw.githubusercontent.com/pixeltable/pixeltable/release/docs/resources/images/000000000034.jpg'},
  {'image': 'https://raw.githubusercontent.com/pixeltable/pixeltable/release/docs/resources/images/000000000057.jpg'}
])

t.select(t.image, t.labels).collect()

When new data is inserted into tables, Pixeltable incrementally runs all computed columns against the new data, ensuring the table is up to date. If you completed the optional LLM Vision step, the descriptions will also be generated automatically for these new images.

What happened behind the scenes?

Pixeltable automatically:

Created a persistent multimodal table
Downloaded and cached the DETR model
Ran inference on your image
Stored all results (including computed columns) for instant retrieval
Will incrementally process any new images you insert

Next Steps

10-Minute Tour

A deeper walkthrough with video, embeddings, and similarity search.

Deployment Overview

Three production patterns: Full Backend (FastAPI + React), Batch Processing (export to your DB), and Declarative Serving (API from TOML).

HTTP Serving

Expose tables and queries as HTTP endpoints with pxt serve or FastAPIRouter.

Create a Project

uvx pixeltable-new myapp — scaffold a full project (serving, backend, or batch) in one command.

Welcome to Pixeltable

Tools

Core Concepts

How-To

System requirements

Installation

Getting help

Build an image analysis app

Next Steps

10-Minute Tour

Deployment Overview

HTTP Serving

Create a Project

​System requirements

​Installation

​Getting help

​Build an image analysis app

​Next Steps

10-Minute Tour

Deployment Overview

HTTP Serving

Create a Project

System requirements

Installation

Getting help

Build an image analysis app

Next Steps