Skip to main content
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 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
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.
For changes to langchain-core:
cd libs/core
uv sync --all-groups
make test  # Ensure tests pass before starting development
For changes to langchain:
cd libs/langchain
uv sync --all-groups
make test  # Ensure tests pass before starting development
For changes to partner integrations:
cd libs/partners/langchain-{partner}
uv sync --all-groups
make test  # Ensure tests pass before starting development
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 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
Located in libs/partners/, these are independently versioned packages for specific integrations. For example:Many partner packages are in external repositories. Please check the list of integrations for details.

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

​
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:
Always preserve:
  • Function signatures and parameter names
  • Class interfaces and method names
  • Return value structure and types
  • Import paths for public APIs
Acceptable modifications:
  • Adding new optional parameters
  • Adding new methods to classes
  • Improving performance without changing behavior
  • Adding new modules or functions
  • 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:
  • 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
  • Use specific exception types
  • Don’t expose sensitive information in error messages
  • Implement proper resource cleanup
  • 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.
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
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.