---
id: stone
version: "3.5.4"
license: MIT
license_treatment: permissive
maintenance: active
---

# stone — Stone is an interface description language (IDL) for APIs.

License: permissive · Maintenance: active · Downloads: 2.3M/mo

## What it is and what it does

Stone is an interface description language (IDL) and code-generation framework developed and actively used by Dropbox for their v2 API. You write your API specification once in Stone's language, then use backends (code generators) to automatically produce client libraries and server stubs in your choice of target languages. The package includes builtin backends for Javascript, Python, Obj-C, Swift, and Typescript, and provides a Python interface for writing custom backends to generate code for any target.

The core problem Stone solves is decoupling API specifications from SDK implementations—instead of maintaining separate SDKs in multiple languages that drift out of sync, you maintain a single spec and regenerate all client libraries from it. It also provides a single source of truth for API documentation and enforces consistency across your API design. Stone makes no assumptions about the protocol layer or RPC framework, focusing purely on data type and endpoint specification.

Use it for:

- Generate client libraries in multiple languages from a single API specification for a multi-platform service.
- Maintain consistency and documentation across multiple language-specific SDKs by regenerating them from a canonical spec.
- Define custom code generators for proprietary or domain-specific languages by implementing a Stone backend.
- Evolve an API specification over time while automatically updating all generated client code to match the new schema.
- Decouple API design from SDK implementation so product teams can define APIs without needing expertise in every target language.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Stone is an interface description language and code generator that lets you define an API specification once and automatically generate client libraries and server code in multiple programming languages.

Yes, if you are building or maintaining an API that needs to be consumed by clients in multiple programming languages. Stone is production-grade, actively maintained, has no known vulnerabilities, and solves a real problem at scale. Install friction is minimal. If you only need SDKs in one or two languages or are not responsible for maintaining API consistency across multiple implementations, it may be overkill.

## Install

pip install stone
uv add stone
poetry add stone

## Installing stone

Before you install: Low friction installation as a pure Python wheel with only two runtime dependencies. The project is actively maintained with a recent release and has been in production use since 2016.

License in practice: MIT license permits commercial and private use with minimal restrictions; you may use, modify, and distribute Stone freely as long as you include the license notice.

Quickstart:

pip install stone
stone -h

Or with manual dependency setup:
pip install packaging Jinja2
python -m stone.cli -h

Requires Python 3.11 or later.

Verify before relying:

- Whether the builtin backends (Javascript, Python, Obj-C, Swift, Typescript) are sufficient for your target languages or if you need to write a custom backend.
- Performance characteristics when processing large or complex API specifications.
- Maturity and stability of the JSON serialization scheme and msgpack support mentioned in the documentation.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.3M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

API specification language, code generator from API specs, IDL for REST APIs, multi-language SDK generator, API definition tool, specification to code generation, api-specification, code-generation, multi-language

[View on SkillFed](https://skillfed.io/packages/stone) · [View on PyPI](https://pypi.org/project/stone/)