> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixeltable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Install Pixeltable, create your first table, add a computed column powered by an LLM, and run your first query in just a few minutes of setup.

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

<Tabs>
  <Tab title="venv">
    <Steps>
      <Step title="Create virtual environment">
        ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        python -m venv .venv
        ```
      </Step>

      <Step title="Activate environment">
        <CodeGroup>
          ```bash Linux/MacOS theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
          source .venv/bin/activate
          ```

          ```bash Windows theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
          .venv\Scripts\activate
          ```
        </CodeGroup>
      </Step>

      <Step title="Install Pixeltable">
        ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        pip install pixeltable
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="uv">
    <Steps>
      <Step title="Install uv">
        Install uv from the [Installing uv](https://docs.astral.sh/uv/getting-started/installation/) guide.
      </Step>

      <Step title="Create environment">
        ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        uv venv --python 3.12
        ```
      </Step>

      <Step title="Activate environment">
        <CodeGroup>
          ```bash Linux/MacOS theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
          source .venv/bin/activate
          ```

          ```bash Windows theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
          .venv\Scripts\activate
          ```
        </CodeGroup>
      </Step>

      <Step title="Install Pixeltable">
        ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        uv pip install pixeltable
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="conda">
    <Steps>
      <Step title="Install Miniconda">
        Download and install from the [Miniconda Installation](https://www.anaconda.com/docs/getting-started/miniconda/main) guide.
      </Step>

      <Step title="Create and activate environment">
        ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        conda create --name pxt python=3.12
        conda activate pxt
        ```
      </Step>

      <Step title="Install Pixeltable">
        ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
        pip install pixeltable
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Getting help

* Join our [Discord Community](https://discord.com/invite/QPyqFYx2UN)
* Report issues on [GitHub](https://github.com/pixeltable/pixeltable/issues)
* Contact [support@pixeltable.com](mailto:support@pixeltable.com)

## Build an image analysis app

<Tip>
  This guide will help you spin up a functioning AI workload in 5 minutes.
</Tip>

<Steps>
  <Step title="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.

    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    pip install torch transformers openai
    ```
  </Step>

  <Step title="Create a Table">
    ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    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})
    ```

    <Note>
      Tables are persistent: your data survives restarts and can be queried anytime.
    </Note>
  </Step>

  <Step title="Add AI Object Detection">
    ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    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)
    ```

    <Note>
      Computed columns run automatically whenever new data is inserted.
    </Note>
  </Step>

  <Step title="Insert Data">
    ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    # 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'}
    ])
    ```

    <Note>
      You can insert images from URLs and/or local paths in any combination.
    </Note>
  </Step>

  <Step title="Query Results">
    ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    # Query results
    t.select(t.image, t.labels).collect()
    ```

    **Expected output:**

    | image    | labels                                        |
    | -------- | --------------------------------------------- |
    | \[Image] | \[car, parking meter, truck, car, car, truck] |
    | \[Image] | \[giraffe, giraffe]                           |
  </Step>

  <Step title="(Optional) Add LLM Vision">
    <Tip>
      You'll need an OpenAI API key to use this step. If you don't have one, you can
      safely skip this step.
    </Tip>

    ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    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()
    ```

    ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    # See the full text of the response in row 0
    t.select(t.response.choices[0].message.content).collect()[0]
    ```

    <Note>
      Pixeltable orchestrates LLM calls for optimized throughput, handling
      rate limiting, retries, and caching automatically.
    </Note>
  </Step>

  <Step title="Insert More Data">
    ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    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()
    ```

    <Note>
      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.
    </Note>
  </Step>
</Steps>

<Accordion title="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
</Accordion>

## Next Steps

<CardGroup cols={2}>
  <Card title="10-Minute Tour" icon="play" href="/overview/ten-minute-tour">
    A deeper walkthrough with video, embeddings, and similarity search.
  </Card>

  <Card title="Deployment Overview" icon="rocket" href="/howto/deployment/overview">
    Three production patterns: Full Backend (FastAPI + React), Batch Processing (export to your DB), and Declarative Serving (API from TOML).
  </Card>

  <Card title="HTTP Serving" icon="globe" href="/howto/deployment/serving">
    Expose tables and queries as HTTP endpoints with `pxt serve` or `FastAPIRouter`.
  </Card>

  <Card title="Create a Project" icon="wand-magic-sparkles" href="https://github.com/pixeltable/pixeltable-new">
    `uvx pixeltable-new myapp` — scaffold a full project (serving, backend, or batch) in one command.
  </Card>
</CardGroup>