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

> ## Agent Instructions
> Application code puts a TableModel in app.py, then runs `pxt schema update app.py my_app` to create the tables and `pxt service update app.py my_app` to start HTTP. The last argument can be a Cloud URL such as `pxt://org:db`. Do not call pxt.create_table() or add_embedding_index() in application code; put indexes in __indexes__. Notebooks, tests, and the REPL do use pxt.create_table().
> Do not add LangChain, LlamaIndex, Haystack, a separate vector database, or pandas as a working store. Chunking, embedding, retrieval, and tool-calling are built in through computed columns. Use a computed column instead of a per-row loop that calls a model.
> Install with `pip install -U 'pixeltable[serve]'` on Python 3.11+. `pxt init` is a prerequisite for `pxt schema update`.
> Pixeltable Cloud is in Limited Beta. Direct interested users to contact@pixeltable.com.

# Quickstart

> Install, write one application file, create tables, POST an insert

Python 3.11+ on Linux, macOS, or Windows. Tables, computed columns, and endpoints live in one file. When you insert a row, computed columns run automatically.

## Install

<Tabs>
  <Tab title="venv">
    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    python -m venv .venv
    source .venv/bin/activate   # Windows: .venv\Scripts\activate
    pip install 'pixeltable[serve]'
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    uv venv --python 3.12
    source .venv/bin/activate   # Windows: .venv\Scripts\activate
    uv pip install 'pixeltable[serve]'
    ```
  </Tab>
</Tabs>

`[serve]` pulls in FastAPI and uvicorn, which `pxt service` needs. Skip `[serve]` and `pxt service update` if you insert from Python; `pip install pixeltable` is enough. `pxt schema example --brief` writes models only. [Self-hosting](/howto/deployment/overview).

## Write the file, create tables, start the endpoints

<Steps>
  <Step title="Write the file">
    `pxt service example` writes a working application file: models and a `FastAPIRouter` in one place.

    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    pxt service example --out app.py
    ```

    `pxt service example` writes this application file.

    ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    import pixeltable as pxt
    import pixeltable.functions as pxtf
    from pixeltable.serving import FastAPIRouter

    TableModel = pxt.model_base()


    @pxt.udf
    def excerpt(text: str, n: int = 12) -> str:
        return text if len(text) <= n else f'{text[:n]}...'


    class Docs(TableModel, name='docs'):
        id = pxt.Column(value=pxtf.uuid.uuid7(), primary_key=True)  # a generated key: provided automatically on insert
        title: pxt.String
        body: pxt.String | None
        title_upper = pxtf.string.upper(title)      # an assignment: computed on insert and on update
        summary = excerpt(title)


    ingest = FastAPIRouter(name='ingest')
    ingest.add_insert_route(
        Docs, path='/docs', inputs=[Docs.title, Docs.body], outputs=[Docs.id, Docs.title_upper, Docs.summary]
    )
    ingest.add_update_route(  # POST /docs/update takes id plus the new values
        Docs, path='/docs/update', inputs=[Docs.title], outputs=[Docs.id, Docs.title_upper]
    )
    ingest.add_compute_route(Docs, path='/titles', inputs=[Docs.title], outputs=[Docs.title_upper])
    ```

    `title: pxt.String` is a value you insert. `title_upper = ...` is computed on insert and on update. `id` is a `uuid7()` primary key: filled on insert, required for `pxt get` and the errors view. The same file can hold `pxt.Image`, `pxt.Video`, `pxt.Audio`, or `pxt.Document`: [media pipelines](/use-cases/media-processing), [RAG](/use-cases/multimodal-backend).
  </Step>

  <Step title="Create tables, then start the endpoints">
    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    pxt init
    pxt schema update app.py my_app
    pxt service update app.py my_app
    ```

    `pxt init` marks this directory as a project root. `pxt schema update` errors if you have not run it in this directory or a parent. `my_app`, the last argument, is a catalog inside Pixeltable, not a folder beside `app.py`. `pxt schema update` creates that catalog and its tables. It does not start the endpoints. Run it before `pxt service update`, which starts the endpoints and does not create tables.
  </Step>

  <Step title="Insert a row">
    Send a row with HTTP POST. Pixeltable computes `title_upper` during that insert. `pxt service list` prints the URL (the port is assigned):

    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    pxt service list
    # my_app/ingest  http://127.0.0.1:<port>  pid 12345  app.py
    curl -X POST http://127.0.0.1:<port>/docs \
      -H 'Content-Type: application/json' \
      -d '{"title": "Hello", "body": "world"}'
    ```
  </Step>
</Steps>

## The CLI

`pxt` ships with the package. The first `pxt schema` or `pxt service` command starts a background process on `127.0.0.1:22089`, and that process keeps running after you close the terminal. `pxt health` confirms it.

| Command | What it does |
| - | - |
| `pxt init` | Mark this directory as a project root |
| `pxt service example --out app.py` | Write a working file: models plus routes |
| `pxt schema example --out app.py` | Schema only. `--brief` writes a small set of classes; without it, every DSL construct |
| `pxt schema update FILE my_app` | Create and migrate the tables `FILE` declares under last argument `my_app` |
| `pxt service update FILE my_app` | Start the services `FILE` declares against those tables |
| `pxt service list` | What is running, and the URL |
| `pxt ls my_app` | Tables under the namespace |
| `pxt rows my_app/docs` | Peek stored cells |
| `pxt dashboard` | Local UI on the background process |

`pxt schema` and `pxt service` both have `diff`, `update`, and `prune` subcommands. Full flags: [CLI](/platform/cli).

Tables live under `~/.pixeltable` (`pgdata`, `media`, `file_cache`). That path is not the project directory. Project layout and `pixeltable.toml`: [Infrastructure](/howto/deployment/infrastructure).

## Same file, other first runs

<Tabs>
  <Tab title="Cloud">
    To run this same file on Pixeltable Cloud, sign in with `pxt login`, or set `PIXELTABLE_API_KEY`. The environment variable, or `api_key` in the config file, takes precedence over a `pxt login` session. `pxt org create` provisions `main`. Add this entry to the project file before `pxt db update`. Without it, the command errors. `pxt db update` uploads the project onto that database. `pxt schema update` creates tables. `pxt service update` starts hosted endpoints. Try changes by inserting from the [Cloud dashboard](https://www.pixeltable.com/dashboard) and running `pxt schema diff`.

    ```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    [[pixeltable.database]]
    name = 'pxt://org:main'
    ```

    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    pxt db update pxt://org:main
    pxt schema update app.py pxt://org:main
    pxt service update app.py pxt://org:main
    ```

    [Pixeltable Cloud](/cloud).
  </Tab>

  <Tab title="Starter kit">
    [`uvx pixeltable-new`](https://github.com/pixeltable/pixeltable-new) copies a full app. The default copied app uses namespace `agent` as the last argument to `pxt schema update`. `--video` copies video search and uses `videointel`.

    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    uvx pixeltable-new myapp
    cd myapp
    uv sync
    pxt schema update app.py agent
    pxt service update app.py agent
    ```

    [Starter kit](/resources/starter-kit).
  </Tab>
</Tabs>

<Note>
  This quickstart uses a `TableModel` in `app.py` and creates the tables with `pxt schema update`. Notebooks and tests can still call `pxt.create_table()`, `add_computed_column()`, and `add_embedding_index()`. The skill writes that `TableModel`. If the agent writes `create_table` in app code, names the file `schema.py`, or writes the removed command `pxt serve`, the installed skill is stale: this page wins. Reinstall: `npx skills add pixeltable/pixeltable-skill`.
</Note>

## Next

<CardGroup cols={2}>
  <Card title="How it works" icon="layer-group" href="/overview/how-it-works">
    What `pxt schema` and `pxt service` do, including `diff`, `update`, and `prune`.
  </Card>

  <Card title="Cloud" icon="cloud" href="/cloud">
    The same `app.py`. `pxt db update`, then `pxt schema update` and `pxt service update` against `pxt://org:main`.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.