Quick Start

The fastest way to get started using Pixeltable

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

1. Create virtual environment

   python -m venv .venv
   
2. Activate environment

   Linux/MacOS

   source .venv/bin/activate
   
3. Install Pixeltable

   pip install pixeltable
   

uv

1. Install uv

   Install uv from the Installing uv guide.

2. Create environment

   uv venv --python 3.12
   
3. Activate environment

   Linux/MacOS

   source .venv/bin/activate
   
4. Install Pixeltable

   uv pip install pixeltable
   

conda

1. Install Miniconda

   Download and install from the Miniconda Installation guide.

2. Create and activate environment

   conda create --name pxt python=3.12
   conda activate pxt
   
3. Install Pixeltable

   pip install pixeltable
   

Getting help

• Join our Discord Community
• Report issues on GitHub
• Contact [e-mail]

Build an image analysis app

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

1. 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
   
2. 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.

3. 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.

4. 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.

5. 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]

6. (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'
   
   t.add_computed_column(
       description=openai.vision(
           prompt="Describe this image in one sentence.",
           image=t.image,
           model='gpt-4o-mini'
       )
   )
   
   t.select(t.image, t.labels, t.description).collect()
   

   # See the full text of the description in row 0
   t.select(t.description).collect()[0]
   

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

7. Insert a few more images.

   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, t.description).collect()
   

   When new data is insterted into tables, Pixeltable incrementally runs all computed columns against the new data, ensuring the table is up to date.

What happened behind the scenes?

Pixeltable automatically:

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