Contributing to code

Code contributions are welcome! Whether you're fixing bugs, adding features, or improving performance, your contributions help deliver a better developer experience for thousands of developers.

Getting started

If you are looking for something to work on, check out the issue labeled "help wanted" in our repos:

Quick fix: submit a bugfix

For simple bugfixes, you can get started immediately:

Full development setup

For ongoing development or larger contributions:

1. Review our contribution guidelines for features, bugfixes, and integrations
2. Set up your environment following our setup guide below
3. Understand the repository structure and package organization
4. Learn our development workflow including testing and linting

Contribution guidelines

Before you start contributing to LangChain projects, take a moment to think about why you want to. If your only goal is to add a "first contribution" to your resume (or if you're just looking for a quick win) you might be better off doing a boot-camp or an online tutorial.

Contributing to open source projects takes time and effort, but it can also help you become a better developer and learn new skills. However, it's important to know that it might be harder and slower than following a training course. That said, contributing to open source is worth it if you're willing to take the time to do things well!

Backwards compatibility

Maintain compatibility via:

New features

We aim to keep the bar high for new features. We generally don't accept new core abstractions from outside contributors without an existing issue that demonstrates an acute need for them. This also applies to changes to infrastructure and dependencies.

In general, feature contribution requirements include:

Security guidelines

Security checklist:

Development environment

Our Python projects use uv for dependency management. Make sure you have the latest version installed.

uv sync --all-groups
make test  # Verify unit tests pass before starting development

Once you've reviewed the contribution guidelines, find the package directory for the component you're working on in the repository structure section below.

Repository structure

Development workflow

Pre-commit hooks

The LangChain and Deep Agents repositories include pre-commit hooks that automatically run formatting, linting, and validation checks before each commit. Install them from the repository root:

pip install pre-commit  # or: uv tool install pre-commit
pre-commit install

The hooks enforce:

• No direct commits to protected branches
• YAML and TOML syntax validation
• Trailing whitespace and end-of-file fixes
• Smart quote and non-standard space normalization
• Per-package make format and make lint

Running tests

We favor unit tests over integration tests when possible. Unit tests run on every pull request, so they should be fast and reliable. Integration tests run on a schedule and require more setup, so they should be reserved for confirming interface points with external services.

Unit tests

Location: tests/unit_tests/

Unit tests cover modular logic that does not require calls to outside APIs. If you add new logic, you should add a unit test. In unit tests, check pre/post processing and mock external dependencies.

Requirements:

• No network calls allowed
• Test all code paths including edge cases
• Use mocks for external dependencies

To run unit tests:

make test

# Or directly:
uv run --group test pytest tests/unit_tests

# To run a specific test:
TEST_FILE=tests/unit_tests/test_imports.py make test

Integration tests

Location: tests/integration_tests/

Integration tests cover logic that requires making calls to outside APIs (often integration with other services).

Integration tests require access to external services/provider APIs (which can cost money) and therefore are not run by default.

Not every code change will require an integration test, but keep in mind that we'll require/run integration tests separately as part of our review process.

Requirements:

• Test real integrations with external services
• Use environment variables for API keys
• Skip gracefully if credentials unavailable

To run integration tests:

make integration_tests

# Or directly:
uv run --group test --group test_integration pytest --retries 3 --retry-delay 1 tests/integration_tests

# To run a specific test:
TEST_FILE=tests/integration_tests/test_openai.py make integration_tests

Code quality standards

Contributions must adhere to the following quality requirements:

def process_documents(
    docs: list[Document],
    processor: DocumentProcessor,
    *,
    batch_size: int = 100
) -> ProcessingResult:
    """Process documents in batches.

    Args:
        docs: List of documents to process.
        processor: Document processing instance.
        batch_size: Number of documents per batch.

    Returns:
        Processing results with success/failure counts.
    """

class ChatAnthropic(BaseChatModel):
    """Interface to Claude chat models.

    See the [usage guide](https://docs.langchain.com/oss/python/integrations/chat/anthropic)
    for tutorials, feature walkthroughs, and examples.

    Args:
        model: Model identifier (e.g., `'claude-sonnet-4-6'`).
        temperature: Sampling temperature between `0` and `1`.
        max_tokens: Maximum number of tokens to generate.
        api_key: Anthropic API key.

            If not provided, reads from the `ANTHROPIC_API_KEY`
            environment variable.
        timeout: Request timeout in seconds.
        max_retries: Maximum number of retries for failed requests.

    Returns:
        A chat model instance that can be invoked with messages.

    Raises:
        ValueError: If the model identifier is not recognized.
        AuthenticationError: If the API key is invalid.

    Example:
        ```python
        from langchain_anthropic import ChatAnthropic

        model = ChatAnthropic(model="claude-sonnet-4-6")
        response = model.invoke("Hello!")
        ```
    """

make format  # Apply formatting
make lint    # Check style and types

Dependencies

LangChain packages distinguish between hard dependencies and optional dependencies to keep packages lightweight and minimize installation overhead for users.

Test writing guidelines

In order to write effective tests, there's a few good practices to follow:

• Use natural language to describe the test in docstrings
• Use descriptive variable names
• Be exhaustive with assertions

def test_document_processor_handles_empty_input():
    """Test processor gracefully handles empty document list."""
    processor = DocumentProcessor()

    result = processor.process([])

    assert result.success
    assert result.processed_count == 0
    assert len(result.errors) == 0

@pytest.mark.requires("openai")
def test_openai_chat_integration():
    """Test OpenAI chat integration with real API."""

    chat = ChatOpenAI()
    response = chat.invoke("Hello")

    assert isinstance(response.content, str)
    assert len(response.content) > 0

def test_retry_mechanism(mocker):
    """Test retry mechanism handles transient failures."""
    mock_client = mocker.Mock()
    mock_client.call.side_effect = [
        ConnectionError("Temporary failure"),
        {"result": "success"}
    ]

    service = APIService(client=mock_client)
    result = service.call_with_retry()

    assert result["result"] == "success"
    assert mock_client.call.call_count == 2

Submitting your PR

Once your tests pass and code meets quality standards:

1. Push your branch and open a pull request
2. Follow the provided PR template
3. Reference related issues using a closing keyword (e.g., Fixes #123)
4. Wait for CI checks to complete

Getting help

Our goal is to have the most accessible developer setup possible. Should you experience any difficulty getting setup, please ask in the community slack or open a forum post.