ncbi-genome-download filters NCBI by taxonomy ID and genus, and the genus filter is a plain string match

It exists because NCBI restructured its FTP

The project is described as a set of scripts to download bacterial and fungal genomes from NCBI after they restructured their FTP a while ago, and it says plainly that the idea was shamelessly stolen from Mick Watson's Kraken downloader scripts, which are specific to actually building a Kraken database, whereas this one focuses on the actual genome downloading.

That origin story explains the scope precisely. The tool does one job, which is to enumerate what NCBI has and fetch the files you want, and it does not try to be a database builder, an annotation pipeline or a workflow manager. If you were going to use the Kraken scripts directly, this is the part you would have had to write yourself.

The usage is a single command with a group argument.

ncbi-genome-download bacteria

That downloads all bacterial RefSeq genomes in GenBank format. Multiple groups are possible, such as `ncbi-genome-download bacteria,viral`, and the README notes that naming a more specific group reduces the download size and the time needed to find the sequences. To see all available groups, use `ncbi-genome-download --help`, or use `all` to check all groups.

That advice about group specificity is a practical warning. The `all` group covers everything NCBI has across every organism group, and enumerating it is a large operation before you have downloaded a single file. A narrower group means less work before the first byte arrives and a smaller set to filter afterwards.

For a quick look at what a filter would select, there is a dry-run option that shows which accessions would be downloaded given your filters, which is the sensible first command to run for any new combination of options.

The filters cover format, section, assembly level and RefSeq category

The filtering vocabulary is where most of the practical value sits, and it is worth going through the options in the order you are likely to need them.

`--section` selects the data section, so `ncbi-genome-download --section genbank fungi` fetches the fungal GenBank genomes rather than the default RefSeq set. `--formats` controls the file format, with `fasta`, `assembly-report` and `all` available, and multiple formats can be requested in one run, for example `ncbi-genome-download --formats fasta,assembly-report viral`.

`--assembly-levels` narrows to the assembly status, so `ncbi-genome-download --assembly-levels complete bacteria` gets only the completed bacterial RefSeq genomes, and multiple levels can be given, such as `complete,chromosome`.

`--refseq-categories` selects the RefSeq category, and `reference` gives you the reference genomes, which is a much smaller set than the full RefSeq catalogue.

`--genera` filters on organism name, with the important caveat that the README states twice, in bold notes, that this is a simple string match on the organism name provided by NCBI only. Quoting matters, and the README says so explicitly: `ncbi-genome-download --genera "Streptomyces coelicolor" bacteria` needs the quotes, because without them the space separates the argument. Multiple genera are supported as a comma separated list, and genus names can also be put in a file, one organism per line, with the path passed to `--genera`.

The fuzzy variant is `--fuzzy-genus`, which matches the value anywhere in the organism name, so `ncbi-genome-download --genera coelicolor --fuzzy-genus bacteria` gets every bacterial genome whose organism name contains coelicolor anywhere.

That combination is a trap worth naming. An exact genus match against the NCBI organism string can behave differently from what you expect when a species name contains the genus as a substring, and the fuzzy match is deliberately looser still. Neither is a taxonomy lookup. They are string filters over a catalogue, and the result set is exactly as good as your understanding of how NCBI writes those names.

Taxonomy IDs are the precise filter, and the safest one

When you need an exact organism, the taxonomy ID options are the ones to reach for.

`--species-taxids` filters on the NCBI species taxonomy ID, so `ncbi-genome-download --species-taxids 562 bacteria` gets all RefSeq genomes belonging to Escherichia coli. `--taxids` filters on the individual assembly taxonomy ID, so `ncbi-genome-download --taxids 511145 bacteria` gets the single RefSeq genome for Escherichia coli str. K-12 substr. MG1655.

Both accept comma separated lists, and both accept a file with one identifier per line, which is the form you want when the list comes from somewhere else. The example given pulls the reference genomes for cat and human, with the human and cat taxids 9606 and 9685, using `ncbi-genome-download --taxids my_taxids.txt --assembly-levels chromosome vertebrate_mammalian`.

The distinction between the two options is the difference between a species and an assembly, and it is the reason `--taxids` gives you one genome while `--species-taxids` gives many. When you are assembling a dataset with one representative per species, `--species-taxids` plus an assembly level of reference or complete is the combination that gives a defensible set, and it is reproducible in a way the genus string match is not, because a numeric identifier does not change meaning when NCBI rewrites an organism name.

The `vertebrate_mammalian` group in that example is worth noting too. The group argument is not limited to bacteria and fungi, and the README's examples span bacteria, viral, fungi and vertebrate_mammalian, so the tool covers the full NCBI organism catalogue rather than a single branch of it.

Parallel downloads and the human readable mirror

Two features matter for anyone running this at volume.

The first is parallelism. If you are on a reasonably fast connection the README suggests running multiple downloads in parallel with `ncbi-genome-download bacteria --parallel 4`. For a full bacterial download that is the difference between minutes and a coffee break, and it is a single flag rather than something you have to orchestrate.

The second is the `--human-readable` option, which creates a human-readable directory structure in parallel to mirroring the layout used by NCBI. The implementation detail that matters is that it uses links to point to the appropriate files in the NCBI directory structure, so it saves file space. The trade-off is portability, and the README is upfront about it: links are not supported on some Windows file systems and on some older versions of Windows.

There is also a re-run behaviour worth knowing. If you re-run a previous download with the `--human-readable` option, the tool will not download any new genome files and will just create the human-readable directory structure, but if any files have changed on the NCBI side, a file download will be triggered. That means the option is idempotent for a stable catalogue and self-healing for a changed one.

The directory mirroring is the feature that makes the downloaded set usable afterwards. The raw NCBI layout is organised by assembly, which does not correspond to any taxonomy you care about, and a symlinked view organised by organism is what turns a pile of files into something you can query.

A small dependency set, an Alpha status and a self-aware release history

The package is deliberately light. The install requirements are `appdirs`, `requests >= 2.4.3` and `tqdm`, which is all you need to enumerate an FTP catalogue, fetch files and show a progress bar. The test requirements add `flake8`, `pytest`, `coverage`, `pytest-cov`, `requests-mock` and `pytest-mock`, and the presence of `requests-mock` tells you the FTP interactions are tested against mocked responses rather than against the live server.

The Makefile is three targets, `unit`, `coverage` and `lint`, and the lint target is a two-stage flake8 with the first pass selecting only the error classes that matter and the second pass reporting style issues as exit-zero with a max complexity of 20.

The console scripts are declared as two entry points pointing at the same function, `ncbi-genome-download` and the shorter `ngd`.

The status classification is Development Status 3, Alpha, which is a fair self-assessment for a tool that talks to a server whose layout has changed before and will change again.

The release history shows a project that has thought about provenance. The releases are 0.3.3 from 2023-07-28, 0.3.2 from 2023-07-24 and 0.3.2.zenodo-init from 2023-07-28, which is a re-release of 0.3.2 for Zenodo, and the repository carries a Zenodo DOI badge and a CITATION.cff file. The last push to the repository was on 2026-04-07 and it is not archived.

The Python support statement is precise, and it is the kind of detail that saves an install. The tool is only developed and tested on Python releases still under active support, which the README lists as 3.9, 3.10, 3.11, 3.12 and 3.13, with no attempt at testing on anything older. Version 0.2.12 was the last to support Python 2.

There is also a Chinese translation of the README at `README-CN.md`, a `contrib/` directory for additional scripts, and a separate `ncbi-genome-download-runner.py` entry point for driving the tool from Python.

Editorial conclusion

Adopt ncbi-genome-download if you routinely need reference genome sets from NCBI and want a scriptable, filterable way to get them without hand browsing the FTP tree. Do not adopt it if you need a guaranteed, reproducible set that is identical next year, because the filters are applied against the live NCBI catalogue and the tool offers no manifest of what it fetched. Verify first that the taxa you care about are present in the section and format you are asking for, that the organism names your genus filter matches are the NCBI strings rather than your own taxonomy, and that the assembly level and RefSeq category you select actually exist for those organisms rather than silently returning an empty set.

Frequently asked questions

Official sources

1. Issues
2. kblin/ncbi-genome-download on GitHub
3. License: Apache-2.0
4. README
5. Releases