docs(sdk): introduce litellm-core and announce leaner installation

blog/introducing_litellm_core/index.md

@@ -0,0 +1,79 @@
+---
+slug: introducing-litellm-core
+title: "Introducing litellm-core: the first step toward a leaner SDK"
+description: "Ongoing work to reduce LiteLLM's dependencies and installation footprint, improve runtime loading, and make imports faster"
+authors:
+  - litellm
+date: 2026-10-08
+---
+
+We're introducing `litellm-core` as the first step in ongoing work to make the LiteLLM SDK leaner. We want applications to install fewer dependencies, use less disk space, and spend less time loading the SDK
+
+This first step delivers an **approximately 65.6 MB reduction** in installed disk space, including runtime dependencies, compared with baseline `litellm` in our source-build comparison. We'll continue building on that progress with further dependency reductions and improvements to how the SDK loads
+
+The first step separates SDK packaging from the existing distribution, removes mandatory AWS and Python Hugging Face tokenizer dependencies from core, and leaves out the bundled dashboard. Your application continues to use `import litellm`
+
+{/* truncate */}
+
+## Why a separate core package
+
+LiteLLM supports a broad range of providers, endpoints, and integrations. An application making ordinary chat completion calls may not need AWS credential handling or Python Hugging Face tokenizers, but those packages have been part of the SDK's default installation
+
+Each mandatory dependency contributes to the installation footprint, and it can bring its own dependencies. Importing modules before they are needed can also add startup work. We want developers to install and load less when their application needs less
+
+`litellm-core` gives us a dedicated distribution to improve that experience while preserving the existing `litellm` package's dependency defaults
+
+## The same SDK APIs
+
+Core is built from the shared LiteLLM SDK sources. It retains provider request and response translation, synchronous and asynchronous completions, streaming, embeddings, token counting, model metadata, and cost calculations. Routing, retries, fallbacks, and consistent provider error handling remain part of the SDK
+
+The broader API surface, including Responses, image, audio, and batch operations, is preserved too. Support still depends on the model and provider, and features with optional dependencies need those packages installed
+
+The package name changes to `litellm-core`, but Python imports continue to use `litellm`. Core does not bundle the Admin UI or expose the gateway CLI entry points
+
+## What changes in this first step
+
+Core no longer requires `boto3`, `tokenizers`, or `huggingface-hub` in every installation. Applications that need AWS credential resolution, request signing, or event-stream decoding can install `boto3`. Applications using Python Hugging Face tokenizer paths can install `tokenizers` and `huggingface-hub`
+
+The shared implementation loads these optional packages at the operations that need them and provides installation guidance when they are missing. The proxy CLI is also deferred rather than imported as part of SDK initialization
+
+Token counting remains available through the supported native and `tiktoken` paths. If a token-counting path falls back to an approximation, it emits a warning so applications can distinguish an estimate from a model-specific count
+
+Core also declares `python-dateutil` directly. Removing three mandatory packages does not mean exactly three fewer installed packages: the total depends on their transitive dependencies and the rest of the application's environment
+
+## Approximately 65.6 MB less installed disk space
+
+Our source-build comparison measured an **approximately 65.6 MB reduction** in installed disk space, including runtime dependencies. This is the first measured step in our ongoing work to reduce what applications need to install
+
+The comparison covers default installations without optional extras. Core retains the shared SDK APIs, excludes bundled dashboard assets and gateway CLI entry points, and makes AWS and Python Hugging Face tokenizer packages optional. Adding those packages changes the installation footprint
+
+### How we measured
+
+- We built baseline `litellm` at [commit 5d207d85](https://github.com/BerriAI/litellm/commit/5d207d85ee547bc323d704bc6aaab901aa0be8b6) and `litellm-core` at [commit 029a626c](https://github.com/BerriAI/litellm/commit/029a626c99ec8c6012512b18ecea075a90db9dcd), then installed their default dependencies in separate clean environments on the same Ubuntu x86_64 machine and CPython version, with matching versions of shared dependencies. These measurements describe those source builds
+- Installed size counts unique files belonging to the SDK and its runtime dependencies, including metadata and scripts. It excludes the interpreter, common tooling, and generated bytecode. MB uses decimal units, with 1 MB equal to 1,000,000 bytes. The reduction measures disk space, not RAM usage or inference speed
+
+## A shared foundation for LiteLLM
+
+Our longer-term direction is for `litellm-core` to become the common SDK foundation for LiteLLM, with `litellm` eventually wrapping it
+
+For developers familiar with [Pydantic's architecture](https://docs.pydantic.dev/latest/internals/architecture/), the separation between `pydantic` and `pydantic-core` is a useful analogy: shared core functionality can evolve behind a familiar public interface
+
+That analogy describes the architectural direction. In this first step, `litellm` and `litellm-core` are independently packaged from shared sources. `litellm` has not yet become a wrapper around core
+
+## Getting started
+
+In a fresh virtual environment, install `litellm-core` and continue using your existing `litellm` imports. Add the optional AWS or Python tokenizer packages if your application uses those features
+
+Choose one distribution per environment. `litellm` and `litellm-core` currently install overlapping Python files and cannot coexist, even at matching versions. Existing applications can continue using `litellm` with its current dependency defaults
+
+The [LiteLLM Core guide](https://docs.litellm.ai/docs/litellm_core) covers installation, dependency choices, and the gateway distinction
+
+## Continuing to make core leaner and faster
+
+Our longer-term goal is to bring the default installation to **around 10 total dependencies, including transitive dependencies**. That is a target for ongoing work, not the dependency count of this first release
+
+We'll continue shrinking the installation footprint and loading runtime dependencies only when the relevant functionality needs them
+
+Faster imports remain a goal of that work, alongside fewer dependencies and a smaller installation. We'll keep measuring progress as we improve how the SDK loads and uses its runtime dependencies
+
+As core becomes the common SDK foundation and `litellm` eventually wraps it, we'll keep measuring these changes so developers can follow the progress

docs/index.md

@@ -32,6 +32,14 @@ import QuickStartBox from '@site/src/components/QuickStartBox';
 uv add litellm
 ```
 
+### A leaner SDK installation
+
+For applications that use the Python SDK directly, `litellm-core` provides the shared SDK with fewer mandatory dependencies and without the bundled dashboard or gateway CLI entry points. Python imports remain unchanged: continue using `litellm`
+
+Install `litellm-core` in a fresh environment instead of installing `litellm`. Add AWS and Python Hugging Face tokenizer packages when your application needs them. The two distributions cannot be installed together because they share the same Python files
+
+See [LiteLLM Core](https://docs.litellm.ai/docs/litellm_core) for installation, package selection, and optional dependencies. Existing `litellm` installations retain their current dependency defaults
+
 To deploy the full AI Gateway (Proxy) with the Admin UI, follow the [Quickstart](./proxy/docker_quick_start.md); it runs as a container and needs no Python setup. To run it from the CLI instead, see the [Gateway Quickstart](./learn/gateway_quickstart.md).
 
 ---

docs/litellm_core.md

@@ -0,0 +1,88 @@
+---
+title: LiteLLM Core
+sidebar_label: LiteLLM Core
+description: Install the LiteLLM SDK with fewer default dependencies and add AWS and Python tokenizer packages when needed
+---
+
+# LiteLLM Core
+
+`litellm-core` packages the LiteLLM Python SDK with fewer mandatory dependencies and without the bundled dashboard or gateway CLI entry points. It uses the same SDK sources and the same `litellm` Python namespace as the `litellm` distribution
+
+## Choose a package
+
+| Package | When to use it |
+| --- | --- |
+| `litellm-core` | Your application calls the SDK directly and you want to install AWS and Python Hugging Face tokenizer dependencies only when needed |
+| `litellm` | You want the existing distribution, its dependency defaults, and its supported installation extras |
+
+For a gateway deployment, follow the [Gateway Quickstart](https://docs.litellm.ai/docs/proxy/docker_quick_start). Core does not provide the `litellm` command or bundled Admin UI
+
+## Install
+
+Install core in a fresh virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install litellm-core
+```
+
+On Windows, activate the environment with `.venv\Scripts\activate` instead
+
+Your Python imports still use `litellm`, including imports such as `from litellm import completion` or `from litellm import Router`. The distribution name is `litellm-core`; there is no change to the public import namespace
+
+:::warning Install one distribution per environment
+
+`litellm` and `litellm-core` install overlapping files. Installing both in the same environment causes `import litellm` to fail, even when their versions match
+
+When moving an application to core, replace `litellm` in its dependency declaration and regenerate its lockfile in a fresh environment. If another dependency requires `litellm`, resolve that requirement before switching
+
+:::
+
+## SDK functionality
+
+Core retains provider request and response translation, synchronous and asynchronous completions, streaming, embeddings, token counting, model metadata, and cost calculations. The shared SDK also includes the Router, retries, fallbacks, and provider error mapping
+
+The package split preserves the broader SDK API surface, including Responses, image, audio, and batch operations. Model and provider support still varies by endpoint, and individual integrations can require additional packages. See [Supported Endpoints](https://docs.litellm.ai/docs/supported_endpoints) and the relevant [provider guide](https://docs.litellm.ai/docs/providers)
+
+## Optional dependencies
+
+Core removes `boto3`, `tokenizers`, and `huggingface-hub` from its mandatory dependencies. It declares `python-dateutil` directly and continues to require packages such as `jsonschema` and `tiktoken`
+
+Install optional packages directly. Core does not currently declare installation extras such as `litellm-core[aws]` or `litellm-core[tokenizers]`
+
+### AWS operations
+
+Install `boto3` for AWS credential resolution, SigV4 signing, and AWS event-stream decoding:
+
+```bash
+python -m pip install boto3
+```
+
+This also installs `botocore`. AWS-dependent features include signed Bedrock requests, SageMaker, Polly, and AWS integrations such as Secrets Manager and S3 logging
+
+Bedrock bearer-token request preparation can work without `botocore`. Streaming paths that decode AWS event streams still require it, so bearer authentication alone does not make every Bedrock operation independent of the AWS packages
+
+### Python Hugging Face tokenizers
+
+Install the Python tokenizer packages when your application uses those paths:
+
+```bash
+python -m pip install tokenizers huggingface-hub
+```
+
+Core retains its native tokenizer implementation and `tiktoken` dependency. Token counting does not universally require the optional Python Hugging Face packages. Where token counting falls back to an approximation, LiteLLM emits a warning; treat that result as an estimate
+
+Missing optional dependencies are reported when the operation requiring them runs, with installation guidance
+
+## Installation footprint
+
+In matching source-build comparisons, `litellm-core` reduced installed size by **32.2%**, saving approximately **65.6 MB** including runtime dependencies
+
+Both builds used version `1.106.0`, matching shared dependency versions, and the same Linux machine and Python interpreter. Measurements cover default installations without optional extras, excluding generated bytecode and common tooling. The source builds were baseline [`5d207d85`](https://github.com/BerriAI/litellm/commit/5d207d85ee547bc323d704bc6aaab901aa0be8b6) and core [`029a626c`](https://github.com/BerriAI/litellm/commit/029a626c99ec8c6012512b18ecea075a90db9dcd)
+
+## Relationship to litellm
+
+Currently, `litellm-core` and `litellm` are independently packaged distributions built from shared sources. Installing or upgrading `litellm` continues to use its existing dependency set
+
+The planned architecture makes `litellm-core` the shared SDK dependency, with `litellm` wrapping it. That relationship is not implemented yet: `litellm` does not currently depend on `litellm-core`. Continue to choose one distribution per environment and use the `litellm` Python import namespace with either package

docs/python_sdk.md

@@ -21,6 +21,8 @@ uv add litellm
 
 You can also use `pip install litellm`.
 
+For a leaner default installation, use [LiteLLM Core](./litellm_core.md) in a fresh environment. It keeps the same `litellm` imports and makes AWS and Python Hugging Face tokenizer dependencies optional. Install one distribution per environment: `litellm` and `litellm-core` cannot coexist
+
 ## Make a request
 
 Set the API key of your provider. Then call `completion()` with a model name in the format `provider/model`:

sidebars.js

@@ -749,6 +749,7 @@ const sidebars = {
       link: { type: "doc", id: "python_sdk" },
       items: [
         { type: "doc", id: "learn/sdk_quickstart", label: "Quickstart" },
+        { type: "doc", id: "litellm_core", label: "LiteLLM Core" },
         {
           type: "category",
           label: "SDK Functions",