Custom References

In addition to the pre-built human and mouse reference packages available in Cloud Analysis, you can upload and use your own custom references in your Cloud Analysis projects.

To use custom references in your analyses, you must upload the the entire output directory produced from running Cell Ranger mkref or Cell Ranger mkvdjref (version 3.1 or above).

Each uploaded custom reference will be stored at no cost for 365 days. If you would like to store your custom references past the free storage limit, you can opt-in to ongoing paid storage at $0.02/GB per month.

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 Reference page.


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

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 or Cell Ranger mkvdjref (version 3.1 or above). 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

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.