litellm/CONTRIBUTING.md

Contributing to LiteLLM

Thank you for your interest in contributing to LiteLLM! We welcome contributions of all kinds - from bug fixes and documentation improvements to new features and integrations.

Checklist before submitting a PR

Here are the core requirements for any PR submitted to LiteLLM:

• Sign the Contributor License Agreement (CLA) - see details
• Keep scope isolated - Your changes should address 1 specific problem at a time
• Prove it works end to end - Paste the commands you ran against a live proxy and their output in the PR - see details

Proxy (Backend) PRs

• Add testing - Adding at least 1 test is a hard requirement - see details
• Ensure your PR passes all checks:
  • Unit Tests - make test-unit
  • Linting / Formatting - make lint

UI PRs

• Ensure the UI builds successfully - npm run build
• Ensure all UI unit tests pass - npm run test
• Add tests for new components or logic - If you are adding a new component or new logic, add corresponding tests

Contributor License Agreement (CLA)

Before contributing code to LiteLLM, you must sign our Contributor License Agreement (CLA). This is a legal requirement for all contributions to be merged into the main repository.

Important: We strongly recommend reviewing and signing the CLA before starting work on your contribution to avoid any delays in the PR process.

Quick Start

1. Setup Your Local Development Environment

# Fork the repository on GitHub (click the Fork button at https://github.com/BerriAI/litellm)
# Then clone your fork locally
git clone https://github.com/YOUR_USERNAME/litellm.git
cd litellm

# Create a new branch for your feature (see "Commit and Branch Conventions" below)
git checkout -b feature/your-feature

# Install development dependencies
make install-dev

# Install git hooks that enforce commit + branch conventions (one-time, opt-in)
make install-hooks

# Verify your setup works
make help

That's it! Your local development environment is ready.

Commit and Branch Conventions

Commits follow Conventional Commits and branches follow Conventional Branches. Run make install-hooks once per clone to enable the local git hooks that enforce these — see the contributor docs for the full type list, examples, the protected-branch bypass list, and how to opt out.

2. Development Workflow

Here's the recommended workflow for making changes:

# Make your changes to the code
# ...

# Format your code (auto-fixes formatting issues)
make format

# Run all linting checks (matches CI exactly)
make lint

# Run unit tests to ensure nothing is broken
make test-unit

# Commit your changes (must follow Conventional Commits — see above)
git add .
git commit -m "feat(scope): your descriptive commit message"

# Push and create a PR (branch must follow Conventional Branches — see above)
git push origin feature/your-feature

Adding Testing

Adding at least 1 test is a hard requirement for all PRs.

Where to Add Tests

Add your tests to the tests/test_litellm/ directory.

• This directory mirrors the structure of the litellm/ directory
• Only add mocked tests - no real LLM API calls in this directory
• For integration tests with real APIs, use the appropriate test directories

File Naming Convention

The tests/test_litellm/ directory follows the same structure as litellm/:

• litellm/proxy/caching_routes.py → tests/test_litellm/proxy/test_caching_routes.py
• litellm/utils.py → tests/test_litellm/test_utils.py

Example Test

import pytest
from litellm import completion

def test_your_feature():
    """Test your feature with a descriptive docstring."""
    # Arrange
    messages = [{"role": "user", "content": "Hello"}]
    
    # Act
    # Use mocked responses, not real API calls
    
    # Assert
    assert expected_result == actual_result

Running Tests and Checks

Running Unit Tests

Run all unit tests (uses parallel execution for speed):

make test-unit

If you're running broader test suites, proxy tests, or anything that touches PostgreSQL-backed fixtures/plugins, install the full local test environment first:

make install-test-deps

This syncs the locked test environment used across the repo, including psycopg v3 plus psycopg-binary (used by pytest-postgresql), psycopg2-binary (used by some proxy E2E tests), and a generated Prisma client for DB-backed proxy tests, so pytest startup matches CI without manual package installs.

Run specific test files:

uv run pytest tests/test_litellm/test_your_file.py -v

Running Linting and Formatting Checks

Run all linting checks (matches CI exactly):

make lint

Individual linting commands:

make format-check       # Check Black formatting
make lint-ruff          # Run Ruff linting
make lint-basedpyright  # Run basedpyright type checking
make check-circular-imports    # Check for circular imports
make check-import-safety       # Check import safety

Apply formatting (auto-fixes issues):

make format

Black formatting is enforced in CI. All PRs must pass the Black formatting check.

• AI coding agents (Claude Code, Copilot, Cursor, etc.): AGENTS.md and CLAUDE.md instruct agents to run poetry run black . before committing.
• VS Code users: Install the Black Formatter extension and enable format-on-save:

  {
    "[python]": {
      "editor.defaultFormatter": "ms-python.black-formatter",
      "editor.formatOnSave": true
    }
  }
  

CI Compatibility

To ensure your changes will pass CI, run the exact same checks locally:

# This runs the same checks as the GitHub workflows
make lint
make test-unit

For exact CI compatibility (pins OpenAI version like CI):

make install-dev-ci     # Installs exact CI dependencies

Available Make Commands

Run make help to see all available commands:

make help                       # Show all available commands
make install-dev               # Install development dependencies
make install-proxy-dev         # Install proxy development dependencies
make install-test-deps         # Install the full local test environment
make format                    # Apply Black code formatting
make format-check              # Check Black formatting (matches CI)
make lint                      # Run all linting checks
make test-unit                 # Run unit tests
make test-integration          # Run integration tests
make test-unit-helm            # Run Helm unit tests

Code Quality Standards

LiteLLM follows the Google Python Style Guide.

Our automated quality checks include:

• Black for consistent code formatting
• Ruff for linting and code quality
• basedpyright for static type checking
• Circular import detection
• Import safety validation

All checks must pass before your PR can be merged.

Common Issues and Solutions

1. Linting Failures

If make lint fails:

1. Formatting issues: Run make format to auto-fix
2. Ruff issues: Check the output and fix manually
3. basedpyright issues: Add proper type hints
4. Circular imports: Refactor import dependencies
5. Import safety: Fix any unprotected imports

2. Test Failures

If make test-unit fails:

1. Check if you broke existing functionality
2. Add tests for your new code
3. Ensure tests use mocks, not real API calls
4. Check test file naming conventions

3. Common Development Tips

• Use type hints: basedpyright requires proper type annotations
• Write descriptive commit messages: Help reviewers understand your changes
• Keep PRs focused: One feature/fix per PR
• Test edge cases: Don't just test the happy path
• Update documentation: If you change APIs, update docs

Proving Your Change Works End to End

Tests are a hard requirement, and they are not the proof that your change works. Reviewers need to see the change behave correctly in the product, so every PR's "Screenshots / Proof of Fix" section must show a real run: the exact commands you sent to a live proxy and the output that came back, against real provider APIs rather than mocks. pytest output does not count as proof, because a passing test only shows that the code does what its own mocks were told to expect.

What a good proof looks like:

1. Boot the proxy locally with your branch and a config containing the model you are touching: uv run litellm --config your_config.yaml --detailed_debug
2. Send the request an actual user would send, with curl, and paste both the command and the response. Include the response headers when cost or routing is involved, since x-litellm-response-cost is what a user sees
3. For a bug fix, do that twice: once at the commit you branched from to show the broken behavior, once on your branch to show the fix. Name both commit hashes
4. If your change can be reached from more than one endpoint (/v1/chat/completions, /v1/responses, /v1/messages), show each one. A fix that only lands on the endpoint you tested is a common review finding
5. If it can stream, show the streaming run too. Usage and cost are assembled on a different path when "stream": true
6. For UI changes, include before and after screenshots and say which page you were on

curl -sD - http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "your-model", "messages": [{"role": "user", "content": "hi"}]}'

Spend and usage claims should be checked against the provider's own numbers where the provider reports them, so the reviewer can see that the gateway agrees with the invoice rather than merely being self-consistent.

Contributing an LLM Provider Integration

Provider work (a new provider, a new parameter, a new usage or cost field) is the most common kind of contribution and the one where PRs most often get reworked. Two things prevent that.

Find the existing machinery before you add plumbing. LiteLLM already has generic paths for moving data between the endpoints, the provider transformations, and cost tracking, and a hand-rolled second path for the same data is the single most common reason a provider PR gets rewritten before merge. Start from ARCHITECTURE.md for where the layers live, then read adr/ for why those layers are shaped the way they are. ADR 0001 covers how provider-specific usage fields reach cost tracking, which is where new billing work usually belongs. If you cannot find a mechanism for what you need, say so in the PR or ask in #pr-review on Slack before building one.

Do not change what a caller sees to make internals easier. Each endpoint promises the schema of the API it emulates, so a /v1/responses caller keeps getting input_tokens and a /v1/chat/completions caller keeps getting prompt_tokens, whatever the provider sent on the wire and whatever cost tracking needs internally. Reshaping a public response to feed an internal consumer is a breaking change for every user of that endpoint.

If your change is itself an architectural decision, for example a new cross-cutting mechanism or a deliberate deviation from a provider's API shape, add an ADR alongside the code using adr/0000-template.md.

Building and Running Locally

LiteLLM Proxy Server

To run the proxy server locally:

# Install proxy dependencies
make install-proxy-dev

# Start the proxy server
uv run litellm --config your_config.yaml

Docker Development

If you want to build the Docker image yourself:

# Build using the non-root Dockerfile
docker build -f docker/Dockerfile.non_root -t litellm_dev .

# Run with your config
docker run \
    -v $(pwd)/proxy_config.yaml:/app/config.yaml \
    -e LITELLM_MASTER_KEY="sk-1234" \
    -p 4000:4000 \
    litellm_dev \
    --config /app/config.yaml --detailed_debug

UI Development

1. Setup Your Local UI Development Environment

# Clone the repo (if you haven't already)
git clone https://github.com/YOUR_USERNAME/litellm.git
cd litellm

# Navigate to the UI dashboard directory
cd ui/litellm-dashboard

# Install dependencies
npm install

# Start the development server
npm run dev

2. Adding UI Tests

If you are adding a new component or new logic, you must add corresponding tests.

3. Running UI Unit Tests

npm run test

4. Building the UI

Ensure the UI builds successfully before submitting your PR:

npm run build

Submitting Your PR

1. Push your branch: git push origin your-feature-branch
2. Create a PR: Go to GitHub and open a pull request against litellm_internal_staging, which is the default base branch. Do not target main.
3. Fill out the PR template: Provide clear description of changes
4. Wait for review: Maintainers will review and provide feedback
5. Address feedback: Make requested changes and push updates
6. Merge: Once approved, your PR will be merged!

Getting Help

If you need help:

• 💬 Join our Discord
• 💬 Join our Slack
• 📧 Email us: ishaan@berri.ai / krrish@berri.ai
• 🐛 Create an issue

What to Contribute

Looking for ideas? Check out:

• 🐛 Good first issues
• 🚀 Feature requests
• 📚 Documentation improvements
• 🧪 Test coverage improvements
• 🔌 New LLM provider integrations

Thank you for contributing to LiteLLM! 🚀