--- updatedAt: 2026-06-22T16:01:10.000Z agentTools: projectIndex: https://docs.hud.io/llms.txt --- # Python Installation Integrate Hud Python SDK for enhanced observability in your application in a few simple steps > 📘 Prerequisites for Hud Integration > > Before integrating Hud, please make sure your application meets the [requirements](/docs/hud-sdk-compatibility-matrix-for-python).
## 1. Install SDK package Run the installation command according to your package manager. ```shell pip pip install hud-sdk ``` ```shell poetry poetry add hud-sdk ``` ```Text uv uv add hud-sdk ```
## 2. Create hud\_config.py Create the following file: ```python hud_config.py import hud_sdk config = hud_sdk.RegisterConfig() # the var name must be config ``` {`
RegisterConfig() Options

RegisterConfig Fields

RegisterConfig controls how Hud instruments your Python service:

include_modules
List of module name patterns to explicitly include for instrumentation. Useful when you want to focus on specific internal packages. Accepts glob-like strings.
Type: List[str] · Default: [] (instrument all first-party code excluding third-party)
max_mapped_functions
Upper bound on the number of functions Hud will map and monitor. Helps keep overhead predictable in very large codebases.
Type: int · Default: 50000
min_pod_memory_mb
Minimum memory threshold in MB expected for the runtime. Hud may adjust behavior if available memory is below this value.
Type: int · Default: 250 MB
max_file_size_bytes
Maximum source file size that Hud will parse when mapping functions. Larger files are skipped to avoid heavy processing.
Type: int · Default: 2097152 bytes (2 MB)
init_timeout
Timeout in seconds for initialization tasks such as mapping and startup handshakes.
Type: int · Default: 30 seconds
verbose
Enables verbose logging from the SDK for debugging and development.
Type: bool · Default: false

Example:

from hud_sdk import RegisterConfig

config = RegisterConfig(
    include_modules=["my_company.*", "internal_pkg"],
    max_mapped_functions=50000,
    min_pod_memory_mb=250,
    max_file_size_bytes=2 * 1024 * 1024,
    init_timeout=30,
    verbose=True
)
`}
## 3. Add Hud CLI to your start command Hud's SDK uses a CLI wrapper to instrument every part of your code. ```shell python python -m hud_run --config ./hud_config.py --key --service main.py ``` ```shell gunicorn hud-run --config ./hud_config.py --key --service gunicorn main:app ``` ```shell hypercorn hud-run --config ./hud_config.py --key --service hypercorn main:app ``` ```shell uvicorn hud-run --config ./hud_config.py --key --service uvicorn main:app ``` ```shell arq hud-run --config ./hud_config.py --key --service arq worker.WorkerSettings ``` ```shell -m hud-run --config ./hud_config.py --key --service python -m module.name ``` > 📘 Tag your deployment (recommended) > > Pass a **deployment ID** so Hud attributes data to a specific code version. You can then filter every page in the web app (and MCP) by version using the **Filters** menu in the top-right corner. > > Pass `deployment_id` to `init_session()`: > > ```python > hud_sdk.init_session(, , deployment_id="v2.4.1") > ``` > > Alternatively, you can set the `HUD_DEPLOYMENT_ID` environment variable. > > Use a value that is **unique per version but low cardinality** — e.g. a semantic version (`v2.4.1`), CI build number (`build-1847`), or git tag (`release-2026-04-06`). Avoid high-cardinality values such as a deployment timestamp. {`
Cannot pass secrets in the command line?
If your deployment environment prevents passing secrets (like API keys or service names) as command line arguments, you can still use hud-run safely by omitting the parameters and initializing Hud within your code.

Run your service using: 
hud-run --config ./hud_config.py python main.py
Then, in your code: 
import hud_sdk

hud_sdk.init_session(<hud_api_key>, <your_service_name>, tags={"region": "us-east", "env": "production"}, deployment_id="v2.4.1")
Call hud_sdk.init_session() early in your code. The tags and deployment_id parameters are optional — use tags to attach key-value metadata for filtering, and deployment_id to attribute data to a specific code version.
`} {`
Cannot use the CLI?
If your environment doesn't allow using the hud-run CLI wrapper, you can start Hud directly from within your Python code: 
import hud_sdk

hud_sdk.register(hud_sdk.RegisterConfig())
hud_sdk.init_session(<hud_api_key>, <your_service_name>, tags={"region": "us-east"}, deployment_id="v2.4.1")
Note: hud_sdk.register should be present as early as possible in your code. Hud will not instrument any files that were loaded before it

Functions in the same file also won't be instrumented - for full coverage, use hud-run.
`}
## 4. Run your service and trigger it! **Start your service and trigger the functions you want to measure** - metrics collection will begin automatically. Then, head over to the [web app](https://www.app.hud.io) to explore your data live, or [install the IDE extension](https://docs.hud.io/docs/install-ide-extension#/) to view it directly alongside your code. {` Need help? Use Hud's SDK troubleshoot guide, Chat with our support team or email us at support@hud.io . `}