attachments Docs DSL Playground Pricing GitHub Sign in

docs

Everything here is runnable — copy any block into a notebook and it works. If you'd rather not write code at all, the playground does all of this in the browser.

Install

$ pip install attachments # core: zero dependencies, text formats work $ pip install attachments[pdf] # add a format when you need it $ pip install attachments[office] # xlsx + docx + pptx $ pip install attachments[all-local] # everything light

The library is Python today. The Artifact contract and DSL grammar are frozen and language-neutral, so R, Julia, and TypeScript clients are planned ports, not rewrites — and the HTTP API works from any language right now.

The one function

>>> from attachments import att >>> att("report.pdf") # a file >>> att("data/") # a folder >>> att("**/*.py") # a glob >>> att("results.zip") # an archive >>> att("https://example.com/paper.pdf") # a URL >>> att("github://owner/repo") # a repository

Every call returns the same thing: Artifacts, a list of plain dictionaries — {text, images, audio, video, meta}. Nothing raises. A file that fails comes back as an artifact with a typed error in meta that says what happened and how to fix it.

>>> a = att("report.pdf") + att("data.xlsx") >>> a.text # everything as one prompt-ready string >>> a.images # extracted images, ready for a model >>> a.errors # anything that failed, as data >>> a.claude("Summarize.") # Claude Messages API format >>> a.openai("Summarize.") # OpenAI Chat Completions format >>> a.chunk(max_chars=2000) # segment-aware chunks for RAG

Options, when you need them

Options live in brackets after the source — or as keyword arguments, your choice. They're per-format; the complete reference is generated from the code, and att.options(".pdf") gives you the same answer at runtime.

>>> att("report.pdf[pages: 1-10, images: true, dpi: 300]") >>> att("data.xlsx[sheet: Sales, rows: 100]") >>> att("interview.mp3[model: small, language: en]") >>> att("report.pdf", pages="1-10", images=True) # same thing

The heavy stuff: local or hosted, your call

OCR and audio transcription need heavy downloads. Install them locally if your machine allows it — or let the free hosted tier handle just those, while everything light keeps running on your machine:

$ pip install attachments[ocr] # local OCR (onnxruntime, ~hundreds of MB) $ pip install attachments[audio] # local transcription (whisper weights)
>>> from attachments import att, configure # or: the hosted tier >>> configure(service_url="https://api.attachments.dev/v1") >>> att("scan.pdf") # OCR'd remotely; same Artifact back

Free: 25 MB per file, 10 requests/minute, in memory, never stored. No key, no signup. Details and limits: pricing.

The command line

$ att report.pdf --pages 1-4 $ att "data.xlsx[sheet: Sales]" --copy # straight to clipboard, paste into any chat $ att . --json # whole folder, machine-readable $ att --options .pdf # what can this format do?

For agents: MCP

$ claude mcp add attachments -- uvx --from "attachments[mcp]" attachments-mcp

Gives any MCP-capable agent the same att() — files, folders, URLs, repos — with images delivered as proper content blocks.

Going deeper