---
title: "How to Import Monomers in Bulk"
slug: "how-to-import-monomers-in-bulk"
status: "update"
updated: 2026-11-03T18:04:57Z
published: 2026-11-03T18:04:57Z
canonical: "docs.discngine.com/how-to-import-monomers-in-bulk"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.discngine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Import Monomers in Bulk

This guide shows how to register many monomers at once from a CSV, Excel or SDF file, follow the import, and fix the rows that failed. The worked example is a small library a peptide project typically needs: two hydrophobic replacements and two PEG linkers, one of them with a deliberate mistake.

**Prerequisites**: the **Manager** or **Administrator** role in Biotoolkit Monomers, and the SMILES of every monomer with its attachment points written as `[*:n]`.

## Step 1: Download the template

On the **Monomers** page, click **Import a file**. The **Import monomers** page opens; the **Import a file** quick action of the **Home** page leads there too. The panel on the right, **What the import does**, summarises the rules, and its **Download the template** button downloads `monomer_import_template.xlsx`. Start from it: the column headers must match exactly, and their order does not matter. **Read the file format** opens **The import file** dialog, with the same template button and every column with an example.

![The import file dialog: the four rules of an import, the Download the template button, and the column table with the required columns, an example and the notes](https://cdn.document360.io/dde9293e-c107-4b3e-9774-9c9c296ed970/Images/Documentation/biotoolkit-monomer-service-import-file-format.png?sv=2026-02-06&spr=https&st=2026-11-11T07%3A49%3A07Z&se=2026-11-11T08%3A49%3A07Z&sr=c&sp=r&sig=H7QQRNaunsC%2FmNwflXPyhxBvd7q0RNJH6FhIYftHozU%3D)

## Step 2: Fill in one row per monomer

The columns:

| Column | Required | Content |
| --- | --- | --- |
| `SYMBOL` | yes | The symbol HELM sequences will use. Unique within your organisation for the polymer type, and not held by a public monomer. |
| `NAME` | yes | Full name. |
| `SMILES` | yes | Structure with `[*:n]` attachment points. |
| `POLYMER_TYPE` | yes | `PEPTIDE`, `RNA` or `CHEM`. |
| `MONOMER_TYPE` | yes | `Backbone` or `Branch`; `Undefined` for `CHEM`. |
| `NATURAL_ANALOG` | for `PEPTIDE` and `RNA` | Single-letter code of the natural residue, for example `L`. `-` for `CHEM`. |
| `AUTHOR` | no | Free text. |
| `RGROUPS` | no | Cap group per attachment point, as `R1:H;R2:OH`. |
| `ALIASES` | no | Other names of the monomer, separated by `/`, as `NMeNva/N-Me-Nva`. Added, never removed. See [How to Manage Monomer Aliases](/public/docs/how-to-manage-monomer-aliases). |

The full column reference is in [Import File Format](/public/docs/monomer-import-file-format).

The example library:

| SYMBOL | NAME | SMILES | POLYMER_TYPE | MONOMER_TYPE | NATURAL_ANALOG | RGROUPS |
| --- | --- | --- | --- | --- | --- | --- |
| `Ahp` | 2-Aminoheptanoic acid | `CCCCC[C@H](N[*:1])C([*:2])=O` | `PEPTIDE` | `Backbone` | `L` | `R1:H;R2:OH` |
| `MeNva` | N-methyl-norvaline | `CCC[C@H](N(C)[*:1])C([*:2])=O` | `PEPTIDE` | `Backbone` | `V` | `R1:H;R2:OH` |
| `PEG2` | Diethylene glycol linker | `[*:1]OCCOCCO[*:2]` | `CHEM` | `Undefined` | `-` | `R1:H;R2:OMe` |
| `PEG3` | Triethylene glycol linker | `[*:1]OCCOCCOCCO[*:2]` | `CHEM` | `Undefined` | `-` | `R1:H;R2:H` |

Three things to check in your own rows:

- **The symbol is free.** The public library already holds the common non-natural residues: norleucine is `Nle`, norvaline is `Nva`, sarcosine is `meG`, 2-aminoisobutyric acid is `Aib`. A row that reuses a public symbol fails, and a row whose structure is already public fails too. Browse the **Monomers** page, or search the name, before inventing a symbol. See [Public Monomers](/public/docs/public-monomers).
- **Attachment points are numbered.** `[*]` without a number is not an attachment point.
- **Cap groups come from the vocabulary.** `H`, `OH`, `NH2`, `Azide` and `Ethynyl` are shipped, and your organisation can add its own on the **Cap groups** page. The `PEG2` row above uses `OMe`, which is not one of them, on purpose: it is the row that will fail. See [Attachment Points and CAP Groups](/public/docs/attachment-points-and-cap-groups).

Save the file as `.xlsx`, `.csv` or `.sdf`. In an SDF, each record is one monomer: its `SMILES` data field is the structure when it has one, otherwise its molfile, and the other data fields carry the other columns; see [Import File Format](/public/docs/monomer-import-file-format).

## Step 3: Upload the file

On the **Import monomers** page, drop the file on the **Drop a file here, or browse** zone or click it to browse, then click **Import the file**. Leave **Register a known structure as an alias** off for a first import: with it on, a row whose structure is already registered becomes an alias of that monomer instead of failing, which is useful once you know the duplicates are naming differences. See [How to Manage Monomer Aliases](/public/docs/how-to-manage-monomer-aliases#turn-a-duplicate-symbol-into-an-alias).

For an SD file, leave **Read stereo without chiral flag as racemic** on unless the file comes from a program that writes single enantiomers without the chiral flag. With it on, a record read from its molfile that draws stereocentres without the flag is registered as a racemate (`&1`), the MDL standard; off, as drawn. See [Enhanced Stereochemistry](/public/docs/enhanced-stereochemistry).

**Import the file** asks for confirmation, recalling how the rows will be registered under these options. Click **Import**. The import runs in the background: the page returns immediately, and the **Import history** report below refreshes every few seconds until the import finishes.

![The Import monomers page: the drop zone, the Register a known structure as an alias and Read stereo without chiral flag as racemic switches, the Import the file button, the What the import does panel, and the Import history report with the finished file, its status Done with errors, its row bar and the 1 error link in the Error file column](https://cdn.document360.io/dde9293e-c107-4b3e-9774-9c9c296ed970/Images/Documentation/biotoolkit-monomer-service-import-page(1).png?sv=2026-02-06&spr=https&st=2026-11-11T07%3A49%3A07Z&se=2026-11-11T08%3A49%3A07Z&sr=c&sp=r&sig=H7QQRNaunsC%2FmNwflXPyhxBvd7q0RNJH6FhIYftHozU%3D)

Each row of **Import history** is one file. **Status** shows where it stands, **Rows** gives the counts under a bar, green for the imported rows and red for the refused ones, **Duration** how long it took, and **Error file** holds the download when rows were refused. Show more columns from the report's **Actions** menu if you want the parsed, imported and refused counts side by side, or the one-line **Summary**.

A short delay between the upload and the appearance of the monomers on the **Monomers** page is normal: each structure is validated and drawn by the Biotoolkit service before it is stored.

## Step 4: Read the outcome

The file above ends with **Status** `Done, with errors` and **Rows** `3 imported, 1 refused, of 4`. The status is about the file: a single refused row is enough for `Done, with errors`, and the three other monomers are in the library all the same.

A row of your file has one of three outcomes:

- **Succeeded, created**. The symbol did not exist for that polymer type in your organisation.
- **Succeeded, updated**. A private monomer with the same symbol and polymer type already existed, and the file's values replaced it. If the structure or the classification changed, the previous state is archived as a version. See [Versioning and Deletion](/public/docs/monomer-versioning-and-deletion).
- **Failed**. The row was rejected. It does not stop the other rows.

Public monomers are never touched by an import, and a row that carries the symbol or the structure of a public monomer fails.

On the **Monomers** page, monomers created by an import show `Unknown` in **Created by**. The **Import history** row is where the uploader is recorded.

## Step 5: Fix the failed rows

When at least one row failed, the **Error file** column of **Import history** shows the number of refused rows as a link, `1 error` here; click it to download the error file. It holds the failed rows of your file with one extra column, `ERROR_MESSAGE`.

For the `PEG2` row it reads:

```
Invalid cap group "OME" for R2. Valid values: Azide, Ethynyl, H, NH2, OH
```

The list holds your organisation's own cap groups too, when it has some.

Correct the value to `R2:H` in your file, keep only that row, and upload it again. Re-importing a row that already succeeded is harmless: it is reported as updated, and no version is written when nothing material changed.

The messages you are most likely to meet:

| Message | Cause |
| --- | --- |
| `Symbol is required`, `Name is required`, `SMILES is required`, `Polymer type is required`, `Monomer type is required` | A mandatory column is empty on that row. |
| `Unknown polymer type: …` / `Unknown monomer type: …` | A value outside the lists. The message ends with the expected values. |
| `Invalid cap group "…" for R2. Valid values: …` | A cap outside the vocabulary. |
| `Invalid R-group format "…". Expected format: R1:H or R2:OH` | A pair in `RGROUPS` is not `label:cap`. |
| `Cannot modify protected public monomer 'Nva' (public seed data)` | A public monomer holds that symbol. Use it, or choose another symbol. |
| `Monomer with this structure is already registered: …` | The same structure is already registered under another symbol, yours or public. If your symbol is just another name for it, import the row again with **Register a known structure as an alias** on. |
| `Monomer with this name is already registered: … (symbol: …)` | Another of your monomers of the polymer type has this `NAME`. |
| `"…" is already an alias of monomer …` | The row's `SYMBOL` is already an alias. Use that monomer, or choose another symbol. |
| `Monomer … was created, but alias "…" was not added: …` | The monomer is in the library, but one name of its `ALIASES` cell is taken by another monomer. Fix the cell and import the row again. |
| `Enhanced stereochemistry on bonds (the MDLV30/STEB… collection …) is not supported …` | An SD record's molfile carries an E/Z or atropisomer group the library cannot store. Register each isomer as its own record. |
| `Axial chirality is not supported (the stereo on atom …) …` | The structure is an atropisomer, an allene or a spiro[3.3]heptane drawn with its axial stereo. Remove that stereo. |
| `The record has no molfile (no 'M END' line)` | An SD record has neither a `SMILES` field nor a molfile. |

If the message is **An error has occurred, check your file format …** at upload time, the file itself could not be read: check the extension, the header row, and that the file is not empty.

## Next steps

- Check a single monomer, or correct one by hand: [How to Create or Edit a Monomer](/public/docs/how-to-create-or-edit-a-monomer).