> This page is for MSA Search, version 2.6.0 (Latest) (default).
> 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
```

### Select 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`, about **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 only uses databases found in that directory and does 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/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 short 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/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 [Configuration](/nim/bionemo/msa-search/configuration).