langchain/openwiki/dev-commands.md at 054a5088830f363321b789df575a8775c67f0fe2

0 Fork 0

mirror of https://github.com/langchain-ai/langchain.git synced 2026-10-05 01:15:09 +03:00

Files

T

github-actions[bot]andnpentrel 42f04f460d docs: update OpenWiki (#40781 )

Automated OpenWiki documentation update.

OpenWiki result: success

When the result is `failure`, this PR intentionally preserves only the
pages completed before the failure. Merge it to make that progress the
baseline for the next scheduled run.

Co-authored-by: npentrel <5212232+npentrel@users.noreply.github.com>

2026-09-28 09:57:48 -04:00

10 KiB

Raw Blame History

type, title, description, tags, sources, generated, verified

type

title

description

Overview

The LangChain Python monorepo uses uv for dependency management, make for task automation, and ruff/mypy for code quality. This page provides a quick reference for common development commands and setup workflows.

Initial Setup

Install Dependencies

Each package in libs/ has its own pyproject.toml and uv.lock. Before running tests or making changes, set up dependencies:

# Install all dependency groups (lint, typing, test, dev)
uv sync --all-groups

# Or install only a specific group
uv sync --group test
uv sync --group lint

The --all-groups flag ensures you have tools for linting, type checking, and testing. See the Contributing Guide in AGENTS.md for detailed development conventions and PR guidelines.

Pre-Commit Setup

The repository uses pre-commit hooks to enforce code quality on commit. Install and configure them once:

pre-commit install

Pre-commit runs automatically on staged files before each commit. To manually trigger hooks:

# Run all hooks on all files
pre-commit run --all-files

# Run a specific hook
pre-commit run ruff --all-files

Pre-Commit Hooks

The .pre-commit-config.yaml defines hooks that enforce:

Standard validation: YAML/TOML syntax checking, proper file endings, no trailing whitespace
Text normalization: Fix curly quotes and non-standard spaces
Per-package format and lint: Each package in libs/ (core, langchain, partners/*) runs make format lint
Version consistency checks: Ensure pyproject.toml versions match source code for langchain-core, langchain, and partner packages

These hooks automatically prevent commits that fail linting or have formatting issues. They use the same Makefiles documented below.

Testing Commands

Run All Unit Tests

# From any package directory
make test

# Example: test langchain_v1
cd libs/langchain_v1 && make test

Unit tests live in tests/unit_tests/ (no network calls allowed). The test target uses pytest with xdist for parallelization and socket restrictions to prevent accidental network calls.

Run a Specific Test File

# Using make
make test TEST_FILE=tests/unit_tests/agents/test_agent.py

# Or using uv directly
uv run --group test pytest tests/unit_tests/agents/test_agent.py

Integration Tests

Integration tests live in tests/integration_tests/ and require network access and API keys. Run them separately:

make integration_tests

Some packages (like langchain_v1) use Docker services (PostgreSQL, Redis) for integration tests:

cd libs/langchain_v1
make test  # starts services, runs tests, stops services

Test in Watch Mode

Auto-re-run tests as you edit code:

make test_watch

This uses pytest-watcher (via the ptw command) and updates snapshots automatically.

Coverage Reports

Generate code coverage reports:

make coverage

This produces xml and term-missing reports, useful for understanding untested code paths.

Linting and Formatting

Run Full Linting Suite

make lint

This runs three checks in order:

Ruff check: Linter for logical errors, naming conventions, and code smells
Ruff format (diff): Format checking (does not modify files)
Mypy: Static type checking

Format Code

make format

This applies ruff format and ruff check --fix to auto-fix formatting and logical issues (e.g., unsorted imports, unused variables).

Ruff-Only Commands

Format and linter can be run separately for faster iteration:

# Check formatting without fixing
ruff check .
ruff format . --diff

# Fix formatting and lint issues
ruff check . --fix
ruff format .

Run from within a package directory or from the repo root. Ruff processes Python and Jupyter notebooks.

Type Checking

Full type checking with mypy:

mypy .

Or use the make target:

make type

This checks all Python files for type errors (e.g., incorrect argument types, missing type hints). Type checking can be slow for large packages; run it with:

# Type check specific file or directory
mypy libs/core/langchain_core/runnables.py

Testing a Single Package

To develop and test a single package in the monorepo:

# Example: work on langchain_v1 core agent system
cd libs/langchain_v1

# Install all dependencies for this package
uv sync --all-groups

# Run all unit tests
make test

# Test specific file or with custom pytest options
make test TEST_FILE=tests/unit_tests/agents/test_create_agent.py

# Format and lint
make format
make lint

# Type check
make type

Each package has its own Makefile with consistent targets. The monorepo's /libs/Makefile provides package-wide commands like regenerating lock files.

Lock File Management

The uv.lock file in each package pins exact dependency versions for reproducible builds. Update locks when dependencies change:

# From a package directory
uv lock

# Or regenerate all package locks
cd libs && make lock

# Verify all locks are up-to-date (CI check)
cd libs && make check-lock

The .pre-commit-config.yaml includes UV_FROZEN = true, which prevents unexpected lock file changes during regular development. Use the commands above when intentionally updating dependencies.

Make Commands Reference

All packages follow the same Makefile structure:

Command	Purpose
`make test`	Run all unit tests (pytest)
`make test TEST_FILE=<path>`	Run tests in a specific file or directory
`make test_watch`	Run tests in watch mode (auto-rerun on changes)
`make integration_tests`	Run integration tests (requires API keys)
`make extended_tests`	Run only tests marked with `@pytest.mark.extended`
`make lint`	Run ruff check + ruff format --diff + mypy
`make format`	Apply ruff format and ruff check --fix
`make type`	Run mypy type checking
`make coverage`	Run tests and generate coverage report
`make help`	Display all available targets

Package-specific commands (see Makefiles in each directory):

langchain_v1: make test_fast, make coverage_agents, make start_services, make stop_services
core: make check_imports, make benchmark
partners/*: make test TEST_FILE=tests/integration_tests/

Common Workflows

Before Committing

# 1. Format code
make format

# 2. Run linting and type checks
make lint

# 3. Run tests
make test

# 4. Commit (pre-commit hooks will run automatically)
git commit

Or let pre-commit do the format/lint:

make test
git add .
pre-commit run --all-files  # or just commit and let hooks run
git commit

Iterative Development

For fast feedback during development:

# Terminal 1: Watch tests
make test_watch

# Terminal 2: Edit code and format
# Changes auto-trigger re-run in Terminal 1
make format

Linting a Changed File

# Lint only files changed in the current branch
make lint_diff
make format_diff

These targets run on git diff output against master.

Type Checking Specific Modules

# Type check a module while developing
mypy libs/langchain_v1/langchain/agents/agent.py

# Type check tests (faster, uses test group)
cd libs/langchain_v1
make lint_tests

Environment Variables

The Makefiles use a few environment variables to control behavior:

Variable	Purpose	Default
`UV_FROZEN`	Prevent lock file changes during `uv sync`	`true` in Makefiles
`TEST_FILE`	Path to test file or directory	`tests/unit_tests/`
`PYTEST_EXTRA`	Extra pytest options	(empty)
`LANGGRAPH_TEST_FAST`	Use in-memory services instead of Docker	`1` (fast) or `0` (full)

Example: Run fast tests with extra pytest verbosity:

make test PYTEST_EXTRA="-vv" TEST_FILE=tests/unit_tests/agents

Troubleshooting

Lock file out of sync

# Regenerate lock
cd libs/<package>
uv lock

# Or check if lock is up-to-date
uv lock --check

Dependencies not installed

# Ensure all groups are installed
uv sync --all-groups

# Or just the test group
uv sync --group test

Tests fail with "no network" error

This is intentional—unit tests have socket restrictions. For integration tests:

make integration_tests

Ruff or mypy not found

# Install lint and typing groups
uv sync --group lint --group typing

Pre-commit hook fails locally but passes in CI

Ensure you're using the same Python version and have all dependency groups installed:

python --version
uv sync --all-groups
pre-commit run --all-files

Contributing Guide: Detailed development conventions, PR templates, and code standards
System Architecture: Three-layer design and module responsibilities
CI/CD Workflows: GitHub Actions automation and release process

10 KiB Raw Blame History