> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-lginte-1765488813-6406a61.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing to code

Code contributions are always 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

<Note>
  Before submitting large **new features or refactors**, please first discuss your ideas in [the forum](https://forum.langchain.com/). This ensures alignment with project goals and prevents duplicate work.

  This does not apply to bugfixes or small improvements, which you can contribute directly via pull requests. See the quickstart guide below.
</Note>

### Quick fix: submit a bugfix

For simple bugfixes, you can get started immediately:

<Steps>
  <Step title="Reproduce the issue">
    Create a minimal test case that demonstrates the bug. Maintainers and other contributors should be able to run this test and see the failure without additional setup or modification
  </Step>

  <Step title="Fork the repository">
    Fork the [LangChain](https://github.com/langchain-ai/langchain) or [LangGraph](https://github.com/langchain-ai/langgraph) repo to your <Tooltip tip="If you fork to an organization account, maintainers will be unable to make edits.">personal GitHub account</Tooltip>
  </Step>

  <Step title="Clone and setup">
    ```bash theme={null}
    git clone https://github.com/your-username/name-of-forked-repo.git

    # For instance, for LangChain:
    git clone https://github.com/parrot123/langchain.git

    # For LangGraph:
    git clone https://github.com/parrot123/langgraph.git
    ```

    ```bash theme={null}
    # Inside your repo, install dependencies
    uv sync --all-groups
    ```

    You will need to install [`uv`](https://docs.astral.sh/uv/) if you haven't previously
  </Step>

  <Step title="Create a branch">
    Create a new branch for your fix. This helps keep your changes organized and makes it easier to submit a pull request later.

    ```bash theme={null}
    git checkout -b your-username/short-bugfix-name
    ```
  </Step>

  <Step title="Write failing tests">
    Add [unit tests](#test-writing-guidelines) that will fail without your fix. This allows us to verify the bug is resolved and prevents regressions
  </Step>

  <Step title="Make your changes">
    Fix the bug while following our [code quality standards](#code-quality-standards). Make the **minimal change necessary** to resolve the issue
  </Step>

  <Step title="Verify the fix">
    Ensure that tests pass and no regressions are introduced. Ensure all tests pass locally before submitting your PR

    ```bash theme={null}
    make lint
    make test

    # For bugfixes involving integrations, also run:
    make integration_tests
    # (You may need to set up API testing credentials)
    ```
  </Step>

  <Step title="Document the change">
    Update docstrings if behavior changes, add comments for complex logic
  </Step>

  <Step title="Submit a pull request">
    Follow the PR template provided. If applicable, reference the issue you're fixing using a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) (e.g. `Fixes #ISSUE_NUMBER`) so that the issue is automatically closed when your PR is merged.
  </Step>
</Steps>

### Full development setup

For ongoing development or larger contributions:

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

***

## Contribution guidelines

Before you start contributing to LangChain, 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

<Warning>
  Breaking changes to public APIs are not allowed except for critical security fixes.

  See our [versioning policy](/oss/python/versioning) for details on major version releases.
</Warning>

Maintain compatibility via:

<AccordionGroup>
  <Accordion title="Stable interfaces">
    **Always preserve**:

    * Function signatures and parameter names
    * Class interfaces and method names
    * Return value structure and types
    * Import paths for public APIs
  </Accordion>

  <Accordion title="Safe changes">
    **Acceptable modifications**:

    * Adding new optional parameters

    * Adding new methods to classes

    * Improving performance without changing behavior

    * Adding new modules or functions
  </Accordion>

  <Accordion title="Before making changes">
    * **Would this break existing user code?**

    * Check if your target is public

    * If needed, is it exported in `__init__.py`?

    * Are there existing usage patterns in tests?
  </Accordion>
</AccordionGroup>

### 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 infra and dependencies.

In general, feature contribution requirements include:

<Steps>
  <Step title="Design discussion">
    Open an issue describing:

    * The problem you're solving
    * Proposed API design
    * Expected usage patterns
  </Step>

  <Step title="Implementation">
    * Follow existing code patterns
    * Include comprehensive tests and documentation
    * Consider security implications
  </Step>

  <Step title="Integration considerations">
    * How does this interact with existing features?
    * Are there performance implications?
    * Does this introduce new dependencies?

    We will reject features that are likely to lead to security vulnerabilities or reports.
  </Step>
</Steps>

### Security guidelines

<Warning>
  Security is paramount. Never introduce vulnerabilities or unsafe patterns.
</Warning>

Security checklist:

<AccordionGroup>
  <Accordion title="Input validation">
    * Validate and sanitize all user inputs
    * Properly escape data in templates and queries
    * Never use `eval()`, `exec()`, or `pickle` on user data, as this can lead to arbitrary code execution vulnerabilities
  </Accordion>

  <Accordion title="Error handling">
    * Use specific exception types
    * Don't expose sensitive information in error messages
    * Implement proper resource cleanup
  </Accordion>

  <Accordion title="Dependencies">
    * Avoid adding hard dependencies
    * Keep optional dependencies minimal
    * Review third-party packages for security issues
  </Accordion>
</AccordionGroup>

***

## Development environment

<Warning>
  Our Python projects use [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for dependency management. Make sure you have the latest version installed.
</Warning>

Once you've reviewed the [contribution guidelines](#contribution-guidelines), set up a development environment for the package(s) you're working on.

<Tabs>
  <Tab title="LangChain" icon="link">
    <AccordionGroup>
      <Accordion title="Core abstractions">
        For changes to `langchain-core`:

        ```bash theme={null}
        cd libs/core
        uv sync --all-groups
        make test  # Ensure tests pass before starting development
        ```
      </Accordion>

      <Accordion title="Main package">
        For changes to `langchain`:

        ```bash theme={null}
        cd libs/langchain
        uv sync --all-groups
        make test  # Ensure tests pass before starting development
        ```
      </Accordion>

      <Accordion title="Partner packages">
        For changes to [partner integrations](/oss/python/integrations/providers/overview):

        ```bash theme={null}
        cd libs/partners/langchain-{partner}
        uv sync --all-groups
        make test  # Ensure tests pass before starting development
        ```
      </Accordion>

      <Accordion title="Community packages">
        For changes to community integrations (located in a [separate repo](https://github.com/langchain-ai/langchain-community)):

        ```bash theme={null}
        cd libs/community/langchain_community/path/to/integration
        uv sync --all-groups
        make test  # Ensure tests pass before starting development
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="LangGraph" icon="circle-nodes">
    WIP - coming soon! In the meantime, follow instructions for LangChain.
  </Tab>
</Tabs>

***

## Repository structure

<Tabs>
  <Tab title="LangChain" icon="link">
    LangChain is organized as a monorepo with multiple packages:

    <AccordionGroup>
      <Accordion title="Core packages" defaultOpen>
        * **[`langchain`](https://github.com/langchain-ai/langchain/tree/master/libs/langchain#readme)** (located in `libs/langchain/`): Main package with chains, agents, and retrieval logic
        * **[`langchain-core`](https://github.com/langchain-ai/langchain/tree/master/libs/core#readme)** (located in `libs/core/`): Base interfaces and core abstractions
      </Accordion>

      <Accordion title="Partner packages">
        Located in `libs/partners/`, these are independently versioned packages for specific integrations. For example:

        * **[`langchain-openai`](https://github.com/langchain-ai/langchain/tree/master/libs/partners/openai#readme)**: [OpenAI](/oss/python/integrations/providers/openai) integrations
        * **[`langchain-anthropic`](https://github.com/langchain-ai/langchain/tree/master/libs/partners/anthropic#readme)**: [Anthropic](/oss/python/integrations/providers/anthropic) integrations
        * **[`langchain-google-genai`](https://github.com/langchain-ai/langchain-google/)**: [Google Generative AI](/oss/python/integrations/chat/google_generative_ai) integrations

        Many partner packages are in external repositories. Please check the [list of integrations](/oss/python/integrations/providers/overview) for details.
      </Accordion>

      <Accordion title="Supporting packages">
        * **[`langchain-text-splitters`](https://github.com/langchain-ai/langchain/tree/master/libs/text-splitters#readme)**: Text splitting utilities
        * **[`langchain-standard-tests`](https://github.com/langchain-ai/langchain/tree/master/libs/standard-tests#readme)**: Standard test suites for integrations
        * **[`langchain-cli`](https://github.com/langchain-ai/langchain/tree/master/libs/cli#readme)**: Command line interface
        * **[`langchain-community`](https://github.com/langchain-ai/langchain-community)**: Community maintained integrations (located in a separate repo)
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="LangGraph" icon="circle-nodes">
    WIP - coming soon! In the meantime, follow instructions for LangChain.
  </Tab>
</Tabs>

***

## Development workflow

### Testing requirements

<Info>
  Directories are relative to the package you're working in.
</Info>

Every code change must include comprehensive tests.

#### Unit tests

**Location**: `tests/unit_tests/`

**Requirements**:

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

```bash theme={null}
make test

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

#### Integration tests

**Location**: `tests/integration_tests/`

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 apart of our review process.

**Requirements**:

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

```bash theme={null}
make integration_tests
```

### Code quality standards

Contributions must adhere to the following quality requirements:

<Tabs>
  <Tab title="Type hints">
    **Required**: Complete type annotations for all functions

    ```python theme={null}
    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.
        """
    ```
  </Tab>

  <Tab title="Documentation">
    **Required**: [Google-style docstrings](https://google.github.io/styleguide/pyguide.html) for all public functions.

    **Guiding principle**: Docstrings describe "what"; docs on this site explain the "how" and "why."

    | Content type                | Location   | Purpose                           |
    | --------------------------- | ---------- | --------------------------------- |
    | Parameter descriptions      | Docstrings | Auto-generates into API reference |
    | Return types and exceptions | Docstrings | API reference                     |
    | Minimal usage example       | Docstrings | Show basic instantiation pattern  |
    | Feature tutorials           | This site  | In-depth walkthroughs             |
    | End-to-end examples         | This site  | Real-world usage patterns         |
    | Conceptual explanations     | This site  | Understanding and context         |

    **Docstrings should contain:**

    1. One-line summary of what the class/function does
    2. Link to this site for tutorials, guides, and usage patterns
    3. Parameter documentation with types and descriptions
    4. Return value description
    5. Exceptions that may be raised
    6. Single minimal example showing basic instantiation/usage as necessary

    <AccordionGroup>
      <Accordion title="Good docstring example">
        ````python theme={null}
        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-5-20250929'`).
                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-5-20250929")
                response = model.invoke("Hello!")
                ```
            """
        ````
      </Accordion>

      <Accordion title="What does NOT belong in docstrings">
        Avoid duplicating content that belongs in OSS docs:

        * **Feature tutorials**: Don't include extended walkthroughs. Instead, link to this site:

          ```python theme={null}
          """
          ...

          See the [extended thinking guide](https://docs.langchain.com/oss/integrations/chat/anthropic#extended-thinking)
          for configuration options.

          ...
          """
          ```

        * **Multiple example variations**: Include one minimal example, then link to comprehensive guides:

          ```python theme={null}
          """
          Example:
              \`\`\`python
              message = HumanMessage(content=[
                  {"type": "image", "url": "https://example.com/image.jpg"}
              ])
              \`\`\`

          See the [multimodal guide](https://docs.langchain.com/oss/integrations/chat/anthropic#multimodal)
          for all supported input formats.
          """
          ```

        * **Conceptual explanations**: Keep to factual parameter descriptions. Link to docs for deeper context.

        * **MkDocs-specific syntax**: Avoid `???+`, accordions, or tabs in docstrings. They don't render in IDEs.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Code style">
    **Automated**: Formatting and linting via [`ruff`](https://docs.astral.sh/ruff/)

    ```bash theme={null}
    make format  # Apply formatting
    make lint    # Check style and types
    ```

    **Standards**:

    * Descriptive variable names
    * Break up complex functions (aim for fewer than 20 lines)
    * Follow existing patterns in the codebase
  </Tab>
</Tabs>

***

## Testing and validation

### Running tests locally

Before submitting your PR, ensure you have completed the following steps. Note that the requirements differ slightly between LangChain and LangGraph.

<Tabs>
  <Tab title="LangChain" icon="link">
    <Steps>
      <Step title="Unit tests">
        ```bash theme={null}
        make test
        ```

        All unit tests must pass
      </Step>

      <Step title="Integration tests">
        ```bash theme={null}
        make integration_tests
        ```

        (Run if your changes affect integrations)
      </Step>

      <Step title="Formatting">
        ```bash theme={null}
        make format
        make lint
        ```

        Code must pass all style checks
      </Step>

      <Step title="Type checking">
        ```bash theme={null}
        make type_check
        ```

        All type hints must be valid
      </Step>

      <Step title="PR submission">
        Push your branch and open a pull request. Follow the provided form template. Note related issues using a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword). After submitting, wait, and check to ensure the CI checks pass. If any checks fail, address the issues promptly - maintainers may close PRs that do not pass CI within a reasonable timeframe.
      </Step>
    </Steps>
  </Tab>

  <Tab title="LangGraph" icon="circle-nodes">
    WIP - coming soon! In the meantime, follow instructions for LangChain.
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="Unit tests">
    ```python theme={null}
    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
    ```
  </Tab>

  <Tab title="Integration tests">
    ```python theme={null}
    @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
    ```
  </Tab>

  <Tab title="Mock usage">
    ```python theme={null}
    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
    ```
  </Tab>
</Tabs>

## 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](https://www.langchain.com/join-community) or open a [forum post](https://forum.langchain.com/).

<Check>
  You're now ready to contribute high-quality code to LangChain!
</Check>

***

<Callout icon="pen-to-square" iconType="regular">
  [Edit the source of this page on GitHub.](https://github.com/langchain-ai/docs/edit/main/src/oss/contributing/code.mdx)
</Callout>

<Tip icon="terminal" iconType="regular">
  [Connect these docs programmatically](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
</Tip>