DNAnexus Platform SDK

The DNAnexus Platform SDK (a.k.a. dx-toolkit) includes the dx command-line client, tools for building and debugging apps, and other utilities for working with DNA data on the platform. Our SDK is released under the Apache v2.0 license.

Note: If you plan to do most of your interaction with the platform via the website, and will use the command-line only to upload files, you probably do not need to download the SDK. The Upload Agent (discussed below) is our specialized tool for uploading to the platform and may be all that you need from this page.

You can download the SDK built for your platform:

Platform Version Download
Ubuntu Linux 14.04 64-bit
Ubuntu Linux 12.04 64-bit
CentOS, Red Hat Enterprise Linux, Scientific Linux 5/6/7 * 64-bit dx-toolkit-v0.233.0-centos-amd64.tar.gz
Mac OS X 64-bit dx-toolkit-v0.233.0-osx.tar.gz
Windows 64-bit dx-toolkit-v0.233.0.exe
See the section Alternative downloads below for alternative ways to install the SDK.


  1. Unpack the SDK:
    tar -xzf dx-toolkit*.tar.gz
    Note: Python 2.7 is required. Command-line tools in the SDK will not work with Python 2.6 or Python 3.
  2. Initialize your environment as follows:
    source dx-toolkit/environment
Congratulations! You are now ready to use the Platform SDK.

What's next:

  • The Command-Line Quickstart will get you started on accessing the platform from the command-line.
  • The Developer Portal contains comprehensive information on how to use the SDK to interact with and write your own applications for the DNAnexus Platform.

Building from source

Download either of the following source packages:

Platform Download
Source package .tar.gz dx-toolkit-v0.233.0-source.tar.gz
Source package .zip

See the file in the archive for build-time dependencies and further installation instructions (or view on Github).

Alternative downloads


The Python components of the SDK (dxpy bindings and most of the command-line tools) are distributed through PyPI. Use pip to download and install the dxpy package:

pip install dxpy
Note: OS X 10.9 users with Python < 2.7.6 from or pythonbrew may encounter Python issue 18458 when using the Python interpreter interactively. Upgrade to Python 2.7.6 or greater to resolve the issue.

Ubuntu APT repository

If you are running Ubuntu 12.04 or later, see Ubuntu Repository for instructions on how to obtain the DNAnexus SDK via APT.

Upgrading the DNAnexus SDK

The dx upgrade command is a useful tool to ensure that the users of the DNAnexus platform have the latest command-line tools and can customize their toolkit to suit the requirements of their project. This command will upgrade your DNAnexus SDK to the latest version recommended. The dx upgrade command can also revert your dx-toolkit to a previous version.

Calling dx upgrade without any arguments will upgrade your DNAnexus SDK to the most recent version. Alternatively, you can provide dx upgrade with a version of the DNAnexus SDK that you would prefer to have installed on your local system.

Upgrading to the latest version:

$ dx upgrade Upgrading to v0.228.0 Downloading dx-toolkit-v0.233.0-osx.tar.gz (using curl -O -L)... % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 9874k 100 9874k 0 0 3279k 0 0:00:03 0:00:03 --:--:-- 3279k Unpacking dx-toolkit-v0.233.0-osx.tar.gz... Backing up version v0.227.1... Moving version v0.228.0 into place... Updated to version v0.228.0. Previous version saved in /Users/user-amy/dnanexus/dx-toolkit/build/v0.227.1. Please close this terminal, open a new terminal, and source the environment file in the dx-toolkit folder

Upgrading to a previous version:

$ dx upgrade v0.225.0

Upload Agent

The Upload Agent is a command-line tool for uploading files to the DNAnexus Platform. It is a fast and convenient alternative to using the web interface for uploading files.


  • Fast Parallel Uploads: Data is uploaded using multiple parallel connections for faster upload speeds.
  • Automatic Compression: Text files (such as FASTA, FASTQ, qseq, and others) can be automatically compressed before upload, for better efficiency.
  • Automated Uploads: No user interaction is required; the client can be used to automate uploads of entire sequencing runs.
  • Resumable Uploads: Previously interrupted uploads can be automatically resumed.
  • Progress Reporting: You can monitor individual file upload progress and also average/instantaneous transfer rates.


The Upload Agent is available pre-built for the three main flavors of operating systems:

Platform Download
Linux dnanexus-upload-agent-1.5.27-linux.tar.gz
Mac OS X
Windows DNAnexus Upload Agent 1.5.27 Installer.exe or


Unpack and run the downloaded file. You should then see a help message.

  • 64-bit Linux:
    $ tar -xzf dnanexus-upload-agent-*-linux.tar.gz
    $ cd dnanexus-upload-agent-*-linux
    $ ./ua
  • Mac OS X
    $ unzip dnanexus-upload-agent-*
    $ cd dnanexus-upload-agent-*-osx
    $ ./ua
  • Windows
    • Unzip the file using your favorite utility
    • Run "ua.exe"
Note for Windows 7/2008 users: If you receive an error message saying: 'schannel: failed to setup extended errors', please install this hotfix from Microsoft.

This program requires that you have an API key. Please create an API key before proceeding.

See the Upload Agent Guide for more info about how to use the tool.

dxR: R Bindings Package

There is a basic R bindings library called dxR with wrapper functions for making API calls. Additional higher-level capabilities are under development.

Note: This package is currently under development and still in flux. Releases may introduce some incompatibilities with previous versions, though we will try to avoid this as much as possible and document when it does occur.

You can download the source package or a precompiled binary for Mac or Windows below.

Platform Download
Package source dxR_0.46.0.tar.gz
Mac OS X dxR_0.46.0.tgz


  1. Install any missing software dependencies. You will need R, as well as the packages RCurl and RJSONIO. You can install these packages from within R with the following commands.
    > install.packages("RCurl")
    > install.packages("RJSONIO")
  2. You should now be able to install the dxR package. You can use the R graphical interface to select and install the downloaded file. Or, you can run the following command using the path to the file you downloaded.
    > install.packages("dxR_*", repos=NULL)
    Alternatively, you can also run the following command from the command-line (outside of R) to install the package.
    You can use the -l flag to specify a local directory in which to install the package if you do not have system permissions to install it for all users. If taking such an approach, you should set your R_LIBS environment variable appropriately if you have not already.
    export R_LIBS='/home/username/path/to/dest/library'
    R CMD INSTALL dxR_* -l $R_LIBS

Last edited by Nicolas Bock, 2017-09-07 21:58:19