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

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. See the quickstart guide below.

Quick fix: submit a bugfix

For simple bugfixes, you can get started immediately:

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. Fork the repository

   Fork the LangChain or LangGraph repo to your personal GitHub account

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

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

   git checkout -b your-username/short-bugfix-name
   

5. Write failing tests

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

6. Make your changes

   Fix the bug while following our code quality standards. Make the minimal change necessary to resolve the issue

7. Verify the fix

   Ensure that tests pass and no regressions are introduced. Ensure all tests pass locally before submitting your PR

   make lint
   make test
   
   # For bugfixes involving integrations, also run:
   make integration_tests
   # (You may need to set up API testing credentials)
   

8. Document the change

   Update docstrings if behavior changes, add comments for complex logic

9. Submit a pull request

   Follow the PR template provided. If applicable, reference the issue you’re fixing using a closing keyword (e.g. Fixes #ISSUE_NUMBER) so that the issue is automatically closed when your PR is merged.

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

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 via:

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?

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:

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

---

Development environment

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

Once you’ve reviewed the contribution guidelines, 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

---

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)

---

Development workflow

Testing requirements

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

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

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

make integration_tests

Code quality standards

Contributions must adhere to the following 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.
    """

---

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.

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

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.