Skip to content

Contribute

What contributions?

  • Documentation contributions are very valuable to us!
  • Examples. Show us what you did with Outlines :)
  • Bug reports with a minimum working examples in the issue tracker
  • Bug fixes are always a pleasure to review.
  • New features. Please start a new discussion, or come chat with us beforehand!

Note that the issue tracker is only intended for actionable items. In doubt, open a discussion or come talk to us.

AI-assisted contributions

We welcome the use of AI tools to help you contribute, but you remain fully responsible for everything you submit:

  • Understand your contribution. A human must review and be able to explain every change before it is submitted. Do not open a PR containing code, tests or documentation you cannot explain or have not reviewed yourself.
  • Keep the code and documentation lean. Match the surrounding style and avoid defensive boilerplate and redundant comments, a common AI-output failure mode. Manually review the changes to ensure none of this creeps in.
  • No automated bots or agents. Do not connect bots, GitHub Apps or Actions that automatically post reviews or comments on issues and PRs. All AI use requires human review before anything is posted; we do not want to clutter our issues and PRs with unnecessary comments.

How to contribute?

Setup

First, fork the repository on GitHub and clone the fork locally:

git clone git@github.com/YourUserName/outlines.git
cd outlines

Create a new virtual environment:

If you are using uv:

uv venv
source .venv/bin/activate
alias pip="uv pip" # ... or just remember to prepend any pip command with uv in the rest of this guide

If you are using venv:

python -m venv .venv
source .venv/bin/activate

If you are using conda:

conda env create -f environment.yml

Then install the dependencies in editable mode, and install the pre-commit hooks:

pip install -e ".[test]"
pre-commit install
If you own a GPU and want to run the vLLM tests you will have to run:

pip install -e ".[test-gpu]"

instead.

Outlines provides optional dependencies for different supported backends, which you can install with

pip install ".[vllm]"

A list of supported optional dependencies can be found in the installation guide.

Using VSCode DevContainer / GitHub Codespaces

If you want a fully pre-configured development environment, you can use VSCode DevContainers or GitHub Codespaces.

VSCode DevContainer

  1. Ensure that the Docker daemon is running on your machine.
  2. Install the Dev Containers extension in VSCode.
  3. Open the Outlines repository in VSCode. When prompted, Reopen in Container (or press F1 and select "Remote-Containers: Reopen in Container").
  4. Run the normal setup steps. Your environment will not complain about missing system dependencies!

GitHub Codespaces

  1. Navigate to the Outlines repository on GitHub.
  2. Click on the Code button and select the Codespaces tab.
  3. Click Create codespace on main (or another branch you are working on).
  4. GitHub will launch a pre-configured cloud development environment.

You will not have access to a GPU, but you'll be able to make basic contributions to the project on the go while using a fully featured web-based IDE.

Before pushing your code

Run the tests:

pytest

And run the code style checks:

pre-commit run --all-files

Contribute to the documentation

To work on the documentation you will need to install the related dependencies:

pip install -r requirements-doc.txt

To build the documentation and serve it locally, run the following command in the repository's root folder:

mkdocs serve

By following the instruction you will be able to view the documentation locally. It will be updated every time you make a change.

Open a Pull Request

Create a new branch on your fork, commit and push the changes:

git checkout -b new-branch
git add .
git commit -m "Changes I made"
git push origin new-branch

Then you can open a pull request on GitHub. It should prompt you to do so. Every subsequent change that you make on your branch will update the pull request.

Do not hesitate to open a draft PR before your contribution is ready, especially if you have questions and/or need feedback. If you need help, come tell us on Discord.