mlstdb

Keep your mlst databases up to date. mlstdb handles OAuth authentication with PubMLST and BIGSdb Pasteur so you can download the latest MLST schemes and build a BLAST database, in two commands.

Full Documentation

Install

conda create -n mlst -c bioconda mlst
conda activate mlst
pip install mlstdb

# From bioconda (include conda-forge for dependencies)
conda install -c conda-forge -c bioconda mlstdb

# Or install both tools together
conda create -n mlst -c conda-forge -c bioconda mlst mlstdb

# From PyPI only
pip install mlstdb

Quick Start

1. Register with each database (one-time setup):

mlstdb connect --db pubmlst
# or use --api-key for pubmlst (currently not available for pasteur)
mlstdb connect --db pubmlst --api-key
mlstdb connect --db pasteur

This opens a browser for OAuth registration. Follow the prompts to authorise mlstdb.

2. Download schemes and build the BLAST database:

mlstdb update

This downloads the curated MLST schemes from both PubMLST and Pasteur and creates a BLAST database.

3. Use with mlst:

mlst --blastdb blast/mlst.fa --datadir pubmlst your_assembly.fasta

That's it. For advanced scheme exploration, custom filtering, and detailed option reference, see the full documentation.

Probing API endpoints

To verify that a specific API endpoint is reachable and your credentials are working, use mlstdb ping:

mlstdb ping https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/schemes/67/profiles_csv --db pubmlst

See the ping documentation for the full reference.

Removing contaminated STs or alleles

Discovered a dodgy sequence type or allele in your local database? You can remove it without re-downloading the whole scheme:

# Remove a single ST (orphaned alleles are cleaned up automatically)
mlstdb purge --scheme salmonella --st 3

# Remove a specific allele (also removes any STs that reference it)
mlstdb purge --scheme salmonella --allele aroC:1

The BLAST database is rebuilt automatically after each purge. See the purge documentation for the full reference.

Caution

• Back up your existing MLST databases before running updates.
• If using mlstdb fetch to build a custom scheme list, double-check that all schemes are compatible with the mlst tool. Not all schemes are validated for use with mlst. The mlst tool is designed for bacterial species only.
• mlstdb purge permanently modifies your local database. Take a backup of your pubmlst/ directory before purging, especially when using --force.

Acknowledgements

Built upon the work of:

• BIGSdb_downloader by Keith Jolley
• pyMLST by Benoit Valot

License

mlstdb was previously licensed under MIT. As of version 0.1.7, it is licensed under GPL v3. Original MIT‑licensed code is preserved and attributed according to MIT terms.

For additional support, please raise an issue.