> This page is for MSA Search, version 2.4.0.
> For other versions, use one of these documentation indexes:
> - 2.6.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/msa-search/2.6.0/llms.txt
> - 2.5.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.5.0/llms.txt
> - 2.4.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.4.0/llms.txt
> - 2.3.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.3.0/llms.txt
> - 2.2.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.2.0/llms.txt
> - 2.1.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.1.0/llms.txt
> - 2.0.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.0.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/bionemo/msa-search/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/bionemo/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/bionemo/_mcp/server.

# Task-Specific Profiles and Custom Databases
To choose a database, you can use task-specific profiles or custom databases.
## Task-Specific Profiles

The MSA Search NIM includes task-specific profiles that download only the databases required for specific use cases. This reduces storage requirements and startup time.

### Listing Available Profiles

To list available profiles:

```bash
docker run -it --entrypoint list-model-profiles nvcr.io/nim/colabfold/msa-search:2
```

Example output:

```
MODEL PROFILES
- Compatible with system:
    - 3087b7ea46d601200c1f90c9246a7aa344e487056286497515900b0924d7853a - databases:pdb70|nim_workspace_hash_v1:ab60c4867c3a8ea0613d73003dd9c7debf99925f57a00573de53f0990be8fcb6
    - 6875cb887326718705de1a4d1200b6043fcbdc0a10584dae64ec9dd724d7e047 - databases:all|nim_workspace_hash_v1:72d640b7ae022cda571cca6ef79d0731b11fd9d9e7f52ea53824ad4b31205e5f
    - 9146beba16db6be936e05104095b8fa6f9b0bd7c08356e5b5f50575cf0dd3e65 - databases:uniref30,pdb70,pdb|nim_workspace_hash_v1:67fe40488c771bb66d49916402f521e3b447ebd505a550c669c99e57f44f5b3f
    - 9a7645c82f54583fd741726cb1faf8de9d3a0e0849b50476590402394041a54e - databases:uniref30|nim_workspace_hash_v1:1cbe92b4f059c31d28389ca0cf1e97fa0b47c04b54d4de0eb3c4f9e392520181
```

### Selecting a Profile

To select a specific profile, use the `NIM_MODEL_PROFILE` environment variable with the profile hash from `list-model-profiles`. The example below uses the **PDB70-only** profile (`databases:pdb70`, roughly **~100 MB** on disk)—a small quick-start choice. Profiles that include Uniref30 (for example the `databases:uniref30` hash) require on the order of **~500 GB**. For more information, refer to [Available Profiles](#available-profiles).

```bash
export LOCAL_NIM_CACHE=~/.cache/nim
mkdir -p "$LOCAL_NIM_CACHE"

docker run -it --rm \
  --runtime=nvidia \
  --gpus all \
  -e NGC_API_KEY \
  -e NIM_MODEL_PROFILE=3087b7ea46d601200c1f90c9246a7aa344e487056286497515900b0924d7853a \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2
```

To verify the selected profile after the service starts:

```bash
curl localhost:8000/v1/metadata | jq
```

### Available Profiles

| Profile Tags | Databases | Best For | Storage |
|--------------|-----------|----------|---------|
| `databases:pdb70` | PDB70 | Minimal profile with PDB sequences clustered at 70% identity. Useful for quick testing. | ~100 MB |
| `databases:uniref30` | Uniref30 | Paired MSA search for protein complexes. Uniref30 is the only database used for species-based sequence pairing. | ~500 GB |
| `databases:uniref30,pdb70,pdb` | Uniref30, PDB70, PDB structures | Structural template search. Includes databases for profile building (Uniref30), template search (PDB70), and mmCIF structure files (PDB). | ~700 GB |
| `databases:all` | Uniref30, ColabFold envdb, PDB70, PDB100, PDB structures | Full MSA search with all available databases. Provides maximum sensitivity and coverage. | ~1.2 TB |

<Note>
Profile hashes may change between NIM releases. Always use `list-model-profiles` to get the current hashes for your version.
</Note>

## Custom Databases

You can use custom or manually downloaded MMSeqs2 databases with the MSA Search NIM by mounting them into the container and configuring the `NIM_MODEL_NAME` environment variable.

<Note>
**Custom databases completely replace the default databases.** When you set `NIM_MODEL_NAME`, the NIM will only use databases found in that directory -- it will not mix custom databases with the default model profile databases. If you need multiple databases, download them individually from NGC and mount them all under the same `NIM_MODEL_NAME` directory.
</Note>

### Prerequisites

Before proceeding, ensure the following prerequisites are met:

- Your databases are in MMSeqs2 format, created using `mmseqs createdb` or compatible tools.
- For GPU Server support (enabled by default), databases must be indexed with `mmseqs createindex`. Refer to [Indexing Databases for GPU Server](/nim/bionemo/msa-search/2.4.0/indexing-databases-for-gpu-server) for instructions. Databases downloaded from NGC are already indexed and ready for GPU Server use.

### Specifying Custom Databases

Mount your custom database directory into the Docker container and set the
`NIM_MODEL_NAME` environment variable inside the container pointing to the
mounted directory.

### Example: Loading a Manually Downloaded Database

You can test this process by manually downloading one of the MSA Search databases and instructing NIM to load it as a custom database. This example uses PDB70, the smallest database, suitable for quick testing.

1. Set the required variables and paths:

```bash
DATABASE=pdb70_220313-m18v1
DATABASE_PATH="$PWD/msa-search_v$DATABASE/pdb70_220313"
```

2. Download the database and adjust permissions (the `ngc` CLI creates owner-only files that the container's `nvs` user cannot read):

```bash
ngc registry model download-version nim/colabfold/msa-search:$DATABASE
chmod -R 755 "$DATABASE_PATH"
```

3. Run the NIM with the appropriate mount points and environment variables:

```bash
docker run -it --rm \
  --runtime=nvidia \
  --gpus all \
  -e NIM_MODEL_NAME=/databases \
  -v "$DATABASE_PATH":/databases/pdb70_220313:ro \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2
```

4. Test the service with a simple query:

```bash
curl http://localhost:8000/biology/colabfold/msa-search/predict \
  -H "Content-Type: application/json" \
  -d '{"sequence": "MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH"}'
```

<Note>
If your custom databases are not indexed for GPU Server, refer to [Indexing Databases for GPU Server](/nim/bionemo/msa-search/2.4.0/indexing-databases-for-gpu-server) for instructions on how to create the required index.
</Note>

<Note>
To mount multiple databases, add additional `-v` flags for each database directory, all under the same `NIM_MODEL_NAME`:
`-v "$DB1_PATH":/databases/db1:ro -v "$DB2_PATH":/databases/db2:ro`
</Note>

### Available Databases

The following databases can be downloaded individually from NGC:

| Database | NGC Model Version | Description |
|----------|-------------------|-------------|
| uniref30_2302 | `uniref30_2302-m18v1` | UniRef30 clustered sequences for profile building |
| colabfold_envdb_202108 | `colabfold_envdb_202108-m18v1` | ColabFold environmental database |
| pdb70_220313 | `pdb70_220313-m18v1` | PDB sequences clustered at 70% identity for template search |
| pdb100_230517 | `pdb100_230517-m18v1` | PDB sequences clustered at 100% identity |
| pdb_20251028 | `pdb_20251028_zip-m18v1` | mmCIF structure files for template search |

### Database Directory Structure

Custom databases should be organized with each database in its own subdirectory under `NIM_MODEL_NAME`. The NIM automatically discovers databases by scanning for MMSeqs2 database files. For example,

```
/databases/
├── pdb70_220313/
│   ├── pdb70_220313.dbtype
│   ├── pdb70_220313.idx
│   └── ...
└── other_database/
    └── ...
```

### Database Discovery

The NIM automatically discovers databases at startup using glob patterns:

**Sequence databases**: The NIM scans for `**/*.idx` files (MMSeqs2 index files). Each `.idx` file found registers a searchable database. The database name is derived from the parent directory name (for example, `pdb70_220313/pdb70_220313.idx` registers as `pdb70_220313`).

**PDB structure archive**: For structural template search, the NIM looks for a `**/pdb*.zip` file containing mmCIF structure files. This archive is used to retrieve 3D structures for template hits.

<Note>
The discovery patterns can be customized using environment variables:
- `NIM_MSA_DB_INDEX_PATTERN`: Pattern for sequence database discovery (default: `**/*.idx`)
- `NIM_MSA_PDB_CIFS_ZIP`: Pattern for PDB structure archive (default: `**/pdb*.zip`)
</Note>

For additional configuration options and environment variables, refer to the [Configuration Guide](/nim/bionemo/msa-search/2.4.0/configuration).