LocalAI/CONTRIBUTING.md

Contributing to LocalAI

Thank you for your interest in contributing to LocalAI! We appreciate your time and effort in helping to improve our project. Before you get started, please take a moment to review these guidelines.

Table of Contents

• Getting Started
  • Prerequisites
  • Setting up the Development Environment
  • Environment Variables
• Contributing
  • Submitting an Issue
  • Development Workflow
  • Creating a Pull Request (PR)
• Coding Guidelines
• Testing
• Documentation
• Community and Communication

Getting Started

Prerequisites

• Go 1.21+ (the project currently uses Go 1.26 in go.mod, but 1.21 is the minimum supported version)
  • Download Go or install via your package manager
  • macOS: brew install go
  • Ubuntu/Debian: follow the official instructions (the apt version is often outdated)
  • Verify: go version
• Git
• GNU Make
• GCC / C/C++ toolchain (required for CGo and native backends)
• Protocol Buffers compiler (protoc) — needed for gRPC code generation

System dependencies by platform

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y build-essential gcc g++ cmake git wget \
  protobuf-compiler libprotobuf-dev pkg-config \
  libopencv-dev libgrpc-dev

CentOS / RHEL / Fedora

sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y cmake git wget protobuf-compiler protobuf-devel \
  opencv-devel grpc-devel

macOS

xcode-select --install
brew install cmake git protobuf grpc opencv wget

Windows

Use WSL 2 with an Ubuntu distribution, then follow the Ubuntu instructions above.

Setting up the Development Environment

1. Clone the repository:

   git clone https://github.com/mudler/LocalAI.git
   cd LocalAI
   

2. Build LocalAI:

   make build
   

   This runs protobuf generation, installs Go tools, builds the React UI, and compiles the local-ai binary. Key build variables you can set:

   Variable	Description	Example
   BUILD_TYPE	GPU/accelerator type (cublas, hipblas, intel, ``)	BUILD_TYPE=cublas make build
   GO_TAGS	Additional Go build tags	GO_TAGS=debug make build
   CUDA_MAJOR_VERSION	CUDA major version (default: 13)	CUDA_MAJOR_VERSION=12

3. Run LocalAI:

   ./local-ai
   

4. Development mode with live reload:

   make build-dev
   

   This installs air automatically and watches for file changes, rebuilding and restarting the server on each save.

5. Containerized build (no local toolchain needed):

   make docker
   

   For GPU-specific Docker builds, see the docker-build-* targets in the Makefile and refer to CLAUDE.md for detailed backend build instructions.

Environment Variables

LocalAI is configured primarily through environment variables (or equivalent CLI flags). The most useful ones for development are:

Variable	Description	Default
LOCALAI_DEBUG	Enable debug mode	false
LOCALAI_LOG_LEVEL	Log verbosity (error, warn, info, debug, trace)	—
LOCALAI_LOG_FORMAT	Log format (default, text, json)	default
LOCALAI_MODELS_PATH	Path to model files	./models
LOCALAI_BACKENDS_PATH	Path to backend binaries	./backends
LOCALAI_CONFIG_DIR	Directory for dynamic config files (API keys, external backends)	./configuration
LOCALAI_THREADS	Number of threads for inference	—
LOCALAI_ADDRESS	Bind address for the API server	:8080
LOCALAI_API_KEY	API key(s) for authentication	—
LOCALAI_CORS	Enable CORS	false
LOCALAI_DISABLE_WEBUI	Disable the web UI	false

See core/cli/run.go for the full list of supported environment variables.

Contributing

We welcome contributions from everyone! To get started, follow these steps:

Submitting an Issue

If you find a bug, have a feature request, or encounter any issues, please check the issue tracker to see if a similar issue has already been reported. If not, feel free to create a new issue and provide as much detail as possible.

Development Workflow

Branch naming conventions

Use a descriptive branch name that indicates the type and scope of the change:

• feature/<short-description> — new functionality
• fix/<short-description> — bug fixes
• docs/<short-description> — documentation changes
• refactor/<short-description> — code refactoring

Commit messages

• Use a short, imperative subject line (e.g., "feat: add whisper backend support", not "Added whisper backend support")
• Keep the subject under 72 characters
• Use the body to explain why the change was made when the subject alone is not sufficient
• Use conventional commits

Creating a Pull Request (PR)

Before jumping into a PR for a massive feature or big change, it is preferred to discuss it first via an issue.

1. Fork the repository.
2. Create a new branch: git checkout -b feature/my-change
3. Make your changes, keeping commits focused and atomic.
4. Run tests locally before pushing (see Testing below).
5. Push to your fork: git push origin feature/my-change
6. Open a pull request against the master branch.
7. Fill in the PR description with:
   • What the change does and why
   • How it was tested
   • Any breaking changes or migration steps
8. Respond to review feedback promptly. Push follow-up commits rather than force-pushing amended commits so reviewers can see incremental changes.
9. Once approved, a maintainer will merge your PR.

Coding Guidelines

This project uses an .editorconfig file to define formatting standards (indentation, line endings, charset, etc.). Please configure your editor to respect it.

For AI-assisted development, see CLAUDE.md for agent-specific guidelines including build instructions and backend architecture details.

General Principles

• Write code that can be tested. All new features and bug fixes should include test coverage.
• Use comments sparingly to explain why code does something, not what it does. Comments should add context that would be difficult to deduce from reading the code alone.
• Keep changes focused. Avoid unrelated refactors, formatting changes, or feature additions in the same PR.

Go Code

• Prefer modern Go idioms — for example, use any instead of interface{}.
• Use golangci-lint to catch common issues before submitting a PR.
• Use github.com/mudler/xlog for logging (same API as slog). Do not use fmt.Println or the standard log package for operational logging.
• Use tab indentation for Go files (as defined in .editorconfig).

Python Code

• Use 4-space indentation (as defined in .editorconfig).
• Include a requirements.txt for any new dependencies.

Code Review

• All contributions go through code review via pull requests.
• Reviewers will check for correctness, test coverage, adherence to these guidelines, and clarity of intent.
• Be responsive to review feedback and keep discussions constructive.

Testing

All new features and bug fixes should include test coverage. The project uses Ginkgo as its test framework.

Running unit tests

make test

This downloads test model fixtures, runs protobuf generation, and executes the full test suite including llama-gguf, TTS, and stable-diffusion tests. Note: some tests require model files to be downloaded, so the first run may take longer.

To run tests for a specific package:

go test ./core/config/...
go test ./pkg/model/...

To run a specific test by name using Ginkgo's --focus flag:

go run github.com/onsi/ginkgo/v2/ginkgo --focus="should load a model" -v -r ./core/

Running end-to-end tests

The e2e tests run LocalAI in a Docker container and exercise the API:

make test-e2e

Running AIO tests

All-In-One images have a set of tests that automatically verify that most of the endpoints work correctly:

# Build the LocalAI docker image
make DOCKER_IMAGE=local-ai docker

# Build the corresponding AIO image
BASE_IMAGE=local-ai DOCKER_AIO_IMAGE=local-ai-aio:test make docker-aio

# Run the AIO e2e tests
LOCALAI_IMAGE_TAG=test LOCALAI_IMAGE=local-ai-aio make run-e2e-aio

Testing backends

To prepare and test extra (Python) backends:

make prepare-test-extra   # build Python backends for testing
make test-extra           # run backend-specific tests

Documentation

We welcome contributions to the documentation. Please open a new PR or create a new issue. The documentation is available under docs/ https://github.com/mudler/LocalAI/tree/master/docs

Gallery YAML Schema

LocalAI provides a JSON Schema for gallery model YAML files at:

core/schema/gallery-model.schema.json

This schema mirrors the internal gallery model configuration and can be used by editors (such as VS Code) to enable autocomplete, validation, and inline documentation when creating or modifying gallery files.

To use it with the YAML language server, add the following comment at the top of a gallery YAML file:

# yaml-language-server: $schema=../core/schema/gallery-model.schema.json

Community and Communication

• You can reach out via the Github issue tracker.
• Open a new discussion at Discussion
• Join the Discord channel Discord