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.

Before submitting large new features or refactors, please first discuss your ideas in the forum. 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. Be sure to link any relevant issues in your PR description. Use closing keywords to automatically close issues when the PR is merged.

New integrations should follow the integration guidelines.

Philosophy

Aim to follow these core principles for all code contributions:

Backwards compatibility

Maintain stable public interfaces and avoid breaking changes

Testing first

Every change must include comprehensive tests to verify correctness and prevent regressions

Code quality

Follow consistent style, documentation, and architecture patterns

Security focused

Prioritize secure coding practices and vulnerability prevention

---

Getting started

Quick fix: submit a bugfix

For simple bugfixes, you can get started immediately:

1. Fork the repository

   Fork the LangChain or LangGraph repo to your personal GitHub account

2. Clone and setup

   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
   

   # Inside your repo, install dependencies
   uv sync --all-groups
   

   You will need to install uv if you haven’t previously.

3. Create a branch

   git checkout -b your-username/short-bugfix-name
   
4. Make your changes

   Fix the bug while following our code quality standards

5. Add tests

   Include unit tests that fail without your fix. This allows us to verify the bug is resolved and prevents regressions

6. Run tests

   Ensure all tests pass locally before submitting your PR

   make lint
   make test
   
   # For bugfixes involving integrations, also run:
   make integration_tests
   
7. Submit a pull request

   Follow the PR template provided. If applicable, reference the issue you’re fixing using a closing keyword (e.g. Fixes #123).

Full development setup

For ongoing development or larger contributions:

1. Development environment

   Set up your environment following our setup guide below

2. Repository structure

   Understand the repository structure and package organization

3. Development workflow

   Learn our development workflow including testing and linting

4. Contribution guidelines

   Review our contribution guidelines for features, bugfixes, and integrations

Development environment

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

Set up a development environment for the package(s) you’re working on.

LangChain

Core abstractions

For changes to langchain-core:

cd libs/core
uv sync --all-groups
make test  # Ensure tests pass before starting development

Main package

For changes to langchain:

cd libs/langchain
uv sync --all-groups
make test  # Ensure tests pass before starting development

Partner packages

For changes to partner integrations:

cd libs/partners/langchain-{partner}
uv sync --all-groups
make test  # Ensure tests pass before starting development

Community packages

For changes to community integrations (located in a separate repo):

cd libs/community/langchain_community/path/to/integration
uv sync --all-groups
make test  # Ensure tests pass before starting development

LangGraph

WIP - coming soon! In the meantime, follow instructions for LangChain.

---

Repository structure

LangChain

LangChain is organized as a monorepo with multiple packages:

Core packages

• langchain (located in libs/langchain/): Main package with chains, agents, and retrieval logic
• langchain-core (located in libs/core/): Base interfaces and core abstractions

Partner packages

Located in libs/partners/, these are independently versioned packages for specific integrations. For example:

• langchain-openai: OpenAI integrations
• langchain-anthropic: Anthropic integrations
• langchain-google-genai: Google Generative AI integrations

Many partner packages are in external repositories. Please check the list of integrations for details.

Supporting packages

• langchain-text-splitters: Text splitting utilities
• langchain-standard-tests: Standard test suites for integrations
• langchain-cli: Command line interface
• langchain-community: Community maintained integrations (located in a separate repo)

LangGraph

WIP - coming soon! In the meantime, follow instructions for LangChain.

---

Development workflow

Testing requirements

Directories are relative to the package you’re working in.

Every code change must include comprehensive tests.

1. Unit tests

   Location: tests/unit_tests/

   Requirements:

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

   make test
   # Or directly:
   uv run --group test pytest tests/unit_tests
   
2. 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.

   Location: tests/integration_tests/

   Requirements:

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

   make integration_tests
   
3. Test quality checklist

   • Tests fail when your code is broken
   • Edge cases and error conditions are tested
   • Proper use of fixtures and mocks

Code quality standards

Quality requirements:

Type hints

Required: Complete type annotations for all functions

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.
    """

Documentation

Required: Google-style docstrings for all public functions

• Document all parameters and return values
• Include usage examples for complex functions
• Document raised exceptions
• Focus on “why” rather than “what”

Code style

Automated: Formatting and linting via ruff

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

Manual formatting and linting

Code formatting and linting are enforced via CI/CD. Run these commands before committing to ensure your code passes checks.

Run formatting and linting:

1. Format code

   make format
   
2. Run linting checks

   make lint
   
3. Verify changes

   Both commands will show you any formatting or linting issues that need to be addressed before committing.

---

Contribution guidelines

Backwards compatibility

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

See our versioning policy for details on major version releases.

Maintain compatibility:

Stable interfaces

Always preserve:

• Function signatures and parameter names
• Class interfaces and method names
• Return value structure and types
• Import paths for public APIs

Safe changes

Acceptable modifications:

• Adding new optional parameters

• Adding new methods to classes

• Improving performance without changing behavior

• Adding new modules or functions

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?

Bugfixes

For bugfix contributions:

1. 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

2. Write failing tests

   Add unit tests that would fail without your fix

3. Implement the fix

   Make the minimal change necessary to resolve the issue

4. Verify the fix

   Ensure that tests pass and no regressions are introduced

5. Document the change

   Update docstrings if behavior changes, add comments for complex logic

New features

We aim to keep the bar high for new features. We generally don’t accept new core abstractions, changes to infra, changes to dependencies, or new agents/chains from outside contributors without an existing issue that demonstrates an acute need for them.

In general, feature contribution requirements include:

1. Design discussion

   Open an issue describing:

   • The problem you’re solving
   • Proposed API design
   • Expected usage patterns
2. Implementation

   • Follow existing code patterns
   • Include comprehensive tests and documentation
   • Consider security implications
3. 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.

Security guidelines

Security is paramount. Never introduce vulnerabilities or unsafe patterns.

Security checklist:

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

Error handling

• Use specific exception types
• Don’t expose sensitive information in error messages
• Implement proper resource cleanup

Dependencies

• Avoid adding hard dependencies
• Keep optional dependencies minimal
• Review third-party packages for security issues

---

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.

LangChain

1. Unit tests

   make test
   

   All unit tests must pass

2. Integration tests

   make integration_tests
   

   (Run if your changes affect integrations)

3. Formatting

   make format
   make lint
   

   Code must pass all style checks

4. Type checking

   make type_check
   

   All type hints must be valid

5. PR submission

   Push your branch and open a pull request. Follow the provided form template. Note related issues using a closing 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.

LangGraph

WIP - coming soon! In the meantime, follow instructions for LangChain.

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

Unit tests

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

Integration tests

@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

Mock usage

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

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.

You’re now ready to contribute high-quality code to LangChain!

---

Edit the source of this page on GitHub.

Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.