Uploading a Custom Reference

Jump to:
Upload a custom reference
Required files

Upload a custom reference with the 10x Genomics Cloud CLI

Use our command line tool to upload custom references to your account. To download and view a tutorial on running commands, visit the 10x Genomics Cloud CLI Documentation page.

Before you upload, make sure your reference meets the requirements:

• It was generated using Cell Ranger mkref 3.1 or higher, Cell Ranger mkvdjref 3.1 or higher, or Cell Ranger ARC mkref 2.0 or higher.
• All the files are contained in a single folder, either compressed as a single tar archive file (.tar.gz/.tgz) or uncompressed.
• All the required files are present. The list of required files can be found here.

Before the upload begins, the 10x Genomics Cloud CLI will verify that your reference meets the above requirements.

Use the command below to upload:

./txg references upload [insert path to reference]

Example upload commands

To upload an uncompressed directory:

./txg references upload /user.name/references/GRCz11/

To upload a tar compressed archive (.tar.gz/.tgz):

./txg references upload /user.name/references/GRCz11.tar.gz

Enter your access token

If this is your first time using the uploader, you will be prompted to provide an access token, which verifies your identity. The access token can be found in your Account Settings.

Confirm and start uploading

If you have provided a path to an uncompressed directory, you will see a message similar to the following:

Verifying all required files are present...

All required files are present.

You are required to upload a compressed directory (.tar.gz). 10x
Genomics Cloud CLI can create a compressed version of the directory
for you. Compression could take several minutes.

Estimated size: Up to 8.5 GB on /Users/path/to/directory/

Would you like to proceed with compressing the directory?
To cancel, press Ctrl+C.

Proceed? [y/N]

After successfully creating the compressed directory, you will see a message similar to the following:

You are about to upload 1 custom reference directory to your 10x
Genomics Cloud account.

Custom reference name: "name-of-reference-directory"
Reference type: [GEX or VDJ]
Cell Ranger mkref version: cellranger-X.Y.Z

/Users/path/to/compressed/reference (8.5 GB)

Total: 8.5 GB


To proceed and delete the compressed directory after uploading, type y.
To proceed with the upload and keep the compressed directory, type k.
To cancel, type N.

Proceed? [y/k/N]

You will receive an email once the upload is complete. The email will be sent to the address associated with your 10x Genomics account.

Once the upload is complete, you can begin to use the reference in analyses in any of your projects. You can also record important details about the reference in Cloud Analysis including the organism, a description, and build notes.

Required files

We require that you upload the entire output directory produced from running Cell Ranger mkref 3.1 or higher, Cell Ranger mkvdjref 3.1 or higher, or Cell Ranger ARC mkref 2.0 or higher. View the full list of required files below.

Gene expression references generated by Cell Ranger mkref

└─ /mkref output/
   ├── reference.json
   ├── /pickle/1
   │   └── genes.pickle1
   ├── /genes/
   │   └── genes.gtf
   ├── /star/
   │   ├── chrLength.txt
   │   ├── chrName.txt
   │   ├── chrNameLength.txt
   │   ├── chrStart.txt
   │   ├── exonGeTrInfo.tab
   │   ├── exoninfo.tab
   │   ├── geneinfo.tab
   │   ├── Genome
   │   ├── genomeParameters.txt
   │   ├── SA
   │   ├── SAindex
   │   ├── sjdbinfo.txt
   │   ├── sjdbList.fromGTF.out.tab
   │   ├── sjdbList.out.tab
   │   └── transcriptinfo.tab
   └── /fasta/
       ├── genome.fa.fai
       └── genome.fa

V(D)J references generated by Cell Ranger mkrefvdj

└─ /mkvdjref output/
   ├── reference.json
   └── /fasta/
       ├── supp_regions.fa
       └── regions.fa

Multiome references generated by Cell Ranger ARC mkref

/mkref output/
├── fasta
│   ├── genome.fa
│   ├── genome.fa.amb
│   ├── genome.fa.ann
│   ├── genome.fa.bwt
│   ├── genome.fa.fai
│   ├── genome.fa.pac
│   └── genome.fa.sa
├── genes
│   └── genes.gtf.gz
├── reference.json
├── regions
│   ├── motifs.pfm      # present if motifs file was supplied
│   ├── transcripts.bed
│   └── tss.bed
└── star
    ├── chrLength.txt
    ├── chrNameLength.txt
    ├── chrName.txt
    ├── chrStart.txt
    ├── exonGeTrInfo.tab
    ├── exonInfo.tab
    ├── geneInfo.tab
    ├── Genome
    ├── genomeParameters.txt
    ├── SA
    ├── SAindex
    ├── sjdbInfo.txt
    ├── sjdbList.fromGTF.out.tab
    ├── sjdbList.out.tab
    └── transcriptInfo.tab

Additional Files

If you provide files beyond the required files (for example, a README file), the files will be uploaded and stored with your reference on Cloud Analysis. Please check and ensure that you only provide files that you wish to include with your custom reference.