# How to Configure OpenMed Settings: Config Files, Profiles, and Environment Variables

> Configure OpenMed settings effectively using TOML files profiles and environment variables. Learn the layered system managed by OpenMedConfig for your OpenMed project.

- Repository: [Maziyar Panahi/openmed](https://github.com/maziyarpanahi/openmed)
- Tags: how-to-guide
- Published: 2026-06-13

---

**OpenMed settings are controlled through a layered configuration system that combines TOML config files, environment-specific profiles, and environment variables, all managed by the `OpenMedConfig` data class in [`openmed/core/config.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/config.py).**

The `maziyarpanahi/openmed` repository provides a flexible configuration architecture for medical NLP workflows. Understanding how to configure OpenMed settings allows you to customize model paths, logging behavior, and inference backends without modifying source code. The system uses a cascading priority where environment variables override profiles, and profiles override the base configuration file.

## Configuration Architecture

OpenMed employs a three-layer configuration strategy. Each layer can override the previous one, giving you fine-grained control over runtime behavior.

### The OpenMedConfig Data Class

At the core of the system is the `OpenMedConfig` dataclass defined in [[`openmed/core/config.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/config.py)](https://github.com/maziyarpanahi/openmed/blob/master/openmed/core/config.py). This class validates and stores all settings, automatically reading environment variables in its `__post_init__` method.

### Base Configuration File

The base configuration lives at `~/.config/openmed/config.toml` by default. You can relocate this file by setting the `OPENMED_CONFIG` environment variable. If the file does not exist at startup, OpenMed creates it with sensible defaults. The path respects the `XDG_CONFIG_HOME` standard if set.

### Profile-Based Configuration

Profiles are TOML fragments stored in `~/.config/openmed/profiles/<profile>.toml`. They override specific values from the base config without replacing the entire file. When `OPENMED_PROFILE` is unset, OpenMed defaults to the **dev** profile (`log_level="DEBUG"`, `timeout=600`). Other built-in profiles include **prod** and **fast**, each optimized for different execution contexts.

### Environment Variable Overrides

Individual fields can be tweaked via environment variables without touching any TOML file:

- `OPENMED_CONFIG` – Path to an alternative base configuration file.
- `OPENMED_PROFILE` – Name of the profile to activate (e.g., `prod`, `fast`).
- `OPENMED_USE_MEDICAL_TOKENIZER` – Set to `0`, `false`, or `no` to disable the medical tokenizer.
- `OPENMED_MEDICAL_TOKENIZER_EXCEPTIONS` – Comma-separated list of terms that should remain unchanged by the tokenizer.
- `HF_TOKEN` – Authentication token for private Hugging Face models.
- `XDG_CONFIG_HOME` – Overrides the base `~/.config` directory.

## Loading Configuration Programmatically

Use `load_config_with_profile()` to initialize the configuration hierarchy. This function automatically respects the `OPENMED_PROFILE` environment variable if set.

```python
from openmed.core.config import load_config_with_profile

# Loads base config + active profile (from env or default 'dev')

config = load_config_with_profile()
print(config.log_level, config.timeout, config.profile)

```

You can also explicitly request a specific profile:

```python

# Force 'prod' profile regardless of environment variables

config = load_config_with_profile(profile_name="prod")

# => log_level="WARNING", timeout=300, profile="prod"

```

For object-oriented workflows, use the `from_profile()` class method:

```python
from openmed.core.config import OpenMedConfig

# Create config from 'fast' profile and override timeout

cfg = OpenMedConfig.from_profile("fast", timeout=200)
print(cfg.log_level)   # "WARNING"

print(cfg.timeout)     # 200

print(cfg.profile)     # "fast"

```

## Managing Profiles

The configuration module provides helper functions to manipulate profile files directly:

```python
from openmed.core.config import list_profiles, get_profile, save_profile, delete_profile

# List available profiles

print(list_profiles())  # ['dev', 'prod', 'test', 'fast']

# Read a profile as a dictionary

profile_data = get_profile('dev')

# Create a new custom profile

save_profile('mycustom', {'log_level': 'ERROR', 'timeout': 30})

# Remove a profile

delete_profile('mycustom')

```

These functions operate on the path defined by `PROFILES_DIR` in the same source file.

## Configuration Fields Reference

The `OpenMedConfig` dataclass exposes the following fields with their default values:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `default_org` | `str` | `"OpenMed"` | Hub organization used when publishing models. |
| `cache_dir` | `Optional[str]` | `~/.cache/openmed` | Directory for downloaded model artifacts. |
| `device` | `Optional[str]` | `None` | Preferred compute device (`cpu`, `cuda`, `mps`, etc.). |
| `hf_token` | `Optional[str]` | Value of `HF_TOKEN` env-var | Token for private Hugging Face repositories. |
| `log_level` | `str` | `"INFO"` | Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`). |
| `timeout` | `int` | `300` | Model-loading timeout in seconds. |
| `use_medical_tokenizer` | `bool` | `True` | Enable medical-aware tokenizer remapping. |
| `medical_tokenizer_exceptions` | `Optional[List[str]]` | `None` | Terms excluded from tokenizer rewriting. |
| `backend` | `Optional[str]` | `None` | Inference backend (`"hf"` for PyTorch/HuggingFace, `"mlx"` for Apple MLX, or `None` for auto-detect). |
| `profile` | `Optional[str]` | `None` | Name of the active profile (populated automatically). |

## Practical Configuration Examples

### Using Environment Variables for One-Off Changes

```bash
export OPENMED_PROFILE=prod
export OPENMED_USE_MEDICAL_TOKENIZER=0
python -c "from openmed.core.config import load_config_with_profile; cfg = load_config_with_profile(); print(cfg.profile, cfg.use_medical_tokenizer)"

```

### Creating a Custom Profile

Create `~/.config/openmed/profiles/custom.toml`:

```toml
log_level = "ERROR"
timeout = 60
backend = "mlx"

```

Then activate it:

```python
config = load_config_with_profile(profile_name="custom")

```

## Summary

- OpenMed configuration is managed by the `OpenMedConfig` class in [`openmed/core/config.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/core/config.py) via a layered system of files, profiles, and environment variables.
- The base config file resides at `~/.config/openmed/config.toml` and can be relocated with `OPENMED_CONFIG` or `XDG_CONFIG_HOME`.
- Profiles are stored in `~/.config/openmed/profiles/`; the default is **dev** when none is specified.
- Use `load_config_with_profile()` to load the full configuration hierarchy, or `OpenMedConfig.from_profile()` for specific profiles.
- Helper functions `list_profiles()`, `get_profile()`, `save_profile()`, and `delete_profile()` provide programmatic profile management.
- Environment variables such as `OPENMED_USE_MEDICAL_TOKENIZER` and `HF_TOKEN` take precedence over file-based settings.

## Frequently Asked Questions

### What happens if I don't set the `OPENMED_PROFILE` environment variable?

If `OPENMED_PROFILE` is unset, OpenMed automatically uses the **dev** profile, which sets `log_level` to `"DEBUG"` and `timeout` to `600` seconds. This behavior is hardcoded in the `load_config_with_profile()` function to ensure verbose debugging during development.

### How do I disable the medical tokenizer without editing configuration files?

Set the environment variable `OPENMED_USE_MEDICAL_TOKENIZER` to `0`, `false`, or `no` before launching your script. The `OpenMedConfig` class reads this variable in its `__post_init__` method and updates the `use_medical_tokenizer` boolean accordingly.

### Can I store the OpenMed configuration in a custom directory?

Yes. Set the `OPENMED_CONFIG` environment variable to the absolute path of your desired TOML file. Alternatively, set `XDG_CONFIG_HOME` to change the base directory from `~/.config` to your preferred location; OpenMed will then look for [`openmed/config.toml`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/config.toml) under that root.

### Where can I find examples of profile usage in the codebase?

The unit tests in [[`tests/unit/test_core.py`](https://github.com/maziyarpanahi/openmed/blob/main/tests/unit/test_core.py)](https://github.com/maziyarpanahi/openmed/blob/master/tests/unit/test_core.py) and [[`tests/unit/test_profiles.py`](https://github.com/maziyarpanahi/openmed/blob/main/tests/unit/test_profiles.py)](https://github.com/maziyarpanahi/openmed/blob/master/tests/unit/test_profiles.py) demonstrate profile creation, loading, and environment variable overrides. These files serve as the authoritative reference for expected configuration behavior.