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

# Infrastructure

> One application file, PIXELTABLE_HOME, and where media files live.

Put `TableModel` classes and `FastAPIRouter` in `app.py`. Put `app.py` in
the directory you run `pxt init` in. `pxt init` writes `pixeltable.toml`,
or appends `[[tool.pixeltable.database]]` to an existing `pyproject.toml`.
`pxt schema update` and `pxt service update` error if you have not run
`pxt init` in this directory or a parent.

<Tree>
  <Tree.Folder name="proj" defaultOpen>
    <Tree.File name="pixeltable.toml" />

    <Tree.File name="app.py" highlight />

    <Tree.File name="functions.py" />
  </Tree.Folder>
</Tree>

`pixeltable.toml` makes `proj` the root. `app.py` imports as `app`.
`from functions import excerpt` works because `functions.py` is a sibling.
A nested file (`ads/app.py`) imports as `ads.app`. Every directory name
on that path has to be a Python identifier. `pxt init` reports names that
are not.

A `pyproject.toml` is a project root only if it has `[tool.pixeltable]`.
If both files sit in the same directory, `pixeltable.toml` wins. `pxt init`
writes one or the other, not both. Nested `pxt init` is refused: one
project, one root.

Create tables, then start HTTP:

```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
```

`my_app` is a namespace inside Pixeltable, not a folder in this repo. A
second file under the same project root can use a different last-argument
name:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pxt schema update ads/app.py ads
pxt schema update docs/app.py docs_app
```

Add another `[[pixeltable.database]]` block for a second database. Leave
`name` off for the local database. For Cloud, set `name = "pxt://org:db"`
and list the files `pxt db update` should upload:

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[[pixeltable.database]]

[[pixeltable.database]]
name = "pxt://org:prod"
include = ["app.py", "functions.py"]
```

Same `app.py`, different last argument:

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

If `app.py` only declares models and a `FastAPIRouter` for Pixeltable,
start HTTP with `pxt service update`, not `python app.py`. If you mount
the router on your own FastAPI app, start that app as in [HTTP serving](/howto/deployment/serving).

Minimum Python and Pixeltable versions:

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[project]
requires-python = ">=3.11"
dependencies = [
    "pixeltable>=0.7.4",
]
```

Pixeltable records each UDF by its import path from the project root, so
renaming or moving the file breaks computed columns that call it.
[Custom functions](/platform/udfs-in-pixeltable). To return computed columns
from an insert, see [HTTP serving](/howto/deployment/serving#return-computed-columns).
Run `pxt schema update` once before you start HTTP processes.

<Card title="Pixeltable Starter Kit" icon="github" href="/resources/starter-kit">
  Two apps. Each ships a Dockerfile and docker-compose.yml.
</Card>

## Where files live

Default home is `~/.pixeltable`: `pgdata` (PostgreSQL), `media` (generated files), `file_cache` (downloads). Names like `my_app` are Pixeltable namespaces (you can also create one with `pxt.create_dir`), not folders in your repo.

* Inserted local files: the path is stored; the original stays put.
* Inserted URLs: the URL is stored; first access downloads into the file cache.
* Generated media: local disk, or the Cloud database's home bucket (`pxtfs://org:db/home`). To use another bucket, set `destination=`, `PIXELTABLE_OUTPUT_MEDIA_DEST`, or `db_output_media_dest` in the database entry.

File cache size is `file_cache_size_g` in `config.toml` only. [Configuration](/platform/configuration).

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# ~/.pixeltable/config.toml
file_cache_size_g = 50
```

If you only insert and export, the Pixeltable data directory can be temporary: write the result out with `export_sql`. [Self-hosting](/howto/deployment/overview). A long-running service needs a persistent volume at `PIXELTABLE_HOME` (pgdata, media, file\_cache). Starter-kit Dockerfiles set `PIXELTABLE_HOME=/data/pixeltable`.

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
PIXELTABLE_INPUT_MEDIA_DEST=s3://your-bucket/input
PIXELTABLE_OUTPUT_MEDIA_DEST=s3://your-bucket/output
```

Or on the database's entry:

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# pixeltable.toml
[[pixeltable.database]]
db_input_media_dest = 's3://your-bucket/input'
db_output_media_dest = 's3://your-bucket/output'
```


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