Comment on page
Download, install, and get started using the DNAnexus Platform SDK, the DNAnexus upload and download agents, and dxCompiler.
The DNAnexus Platform SDK - also called
dx-toolkit- includes the
dxcommand-line client; tools for building and debugging apps; utilities for working with DNA data on the DNAnexus Platform; and Python, Java, C++ and R bindings for working on the DNAnexus Platform.
If you plan to rely on the user interface to interact with the Platform, using the command-line interface only to upload files, you likely don't need to download the full SDK. The Upload Agent may be enough to meet your needs.
pip3 install dxpy
If you see a warning similar to the one below, please update your PATH environment variable to include the path where pip3 installed the new commands.
WARNING: The scripts dx, dx-app-wizard, dx-build-app and dx-build-applet are installed in
'/Users/user-amy/Library/Python/3.9/bin' which is not on PATH.
Consider adding this directory to PATH
If you're using Z shell (zsh), which is included in recent versions of OS X, enable tab completion by entering the following command, or adding it to your
autoload -Uz compinit && compinit
autoload bashcompinit && bashcompinit
eval "$(register-python-argcomplete dx|sed 's/-o default//')"
If you're not using Z shell (zsh), enable tab completion by entering the following command, or add it to your
eval "$(register-python-argcomplete dx|sed 's/-o default//')"
To upgrade the
dxpypackage after installing it using pip3, enter the command:
pip3 install --upgrade dxpy.
If you're using the OS X Xcode command line tools and running Python 3, the psutil dependency may fail to compile. To prevent this from happening, set
export ARCHFLAGS="-arch x86_64"before installing
To avoid character set problems when running the
dxcommand, set the PYTHONIOENCODING environment variable to UTF-8 as follows:
The Java, R, and C++ SDK is available for the following platforms:
Start by unpacking the SDK:
$ tar -xzf dx-toolkit*.tar.gz
Next, if you are using
zshon OS X, update your
~/.zshrcfile as follows:
echo "autoload -Uz compinit && compinit" >> ~/.zshrc && source ~/.zshrc
Then initialize your environment:
$ cd dx-toolkit && source environment
Windows 10 and later versions are supported.
Start the installation by running the command
Systems with Windows Defender enabled may present a warning before launching the
dx-toolkitinstaller. If you see this warning window, click More Info, then choose Run Anyway.
After the installation is complete, find and click on the DNAnexus CLI shortcut on the Windows Start Menu.
The Python package "python-certifi-win32" is needed (use
pip install python-certifi-win32command to install it) if you encounter the following errors during certain operations (e.g.
dx head file-xxx):
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1108)
$ dx upgrade
Upgrading to v0.325.1
Downloading dx-toolkit-v0.325.1-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
Backing up version v0.227.1...
Moving version v0.306.0 into place...
upgrade.sh: Updated to version v0.306.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
You can also run
dx upgradeif you want to revert to a previous version of the SDK, by adding the version number as an argument:
$ dx upgrade v0.225.0
Download either of the following source packages:
dx-toolkitto a proxy, set the
HTTPS_PROXYenvironment variable to an appropriate value:
dx-toolkituses certificates installed on your system to create secure connections. If your system requires an additional TLS certificate, and
dx-toolkitdoesn't appear to be using a certificate installed on your system, you have two options. The first, and most secure, is to set the
DX_CA_CERTenvironment variable to the path of the PEM-encoded TLS certificate file required by your parent organization. The second option is to connect insecurely, avoiding certificate verification altogether, by setting
When using Windows, environments can be customized in a wide variety of ways. As a result, issues can arise even when using the TLS settings detailed in the previous paragraph. Contact DNAnexus Support if you are using Windows and have trouble connecting through a proxy.
The DNAnexus Upload Agent is a command-line tool for uploading files to the DNAnexus Platform. Using the Upload Agent is a fast and convenient alternative to uploading files via the Platform UI.
- Fast Parallel Uploads - Data is uploaded using multiple parallel connections for faster upload speeds.
- Automatic Compression - Text files (such as FASTA, FASTQ, qseq, and other text files) can be automatically compressed before upload, for greater 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 - Users can monitor the progress of individual file uploads, as well as average/instantaneous transfer rates.
The Upload Agent is available pre-built for 64-bit Linux, OS X, and Windows.
Install the Upload Agent on 64-bit Linux as follows:
https://dnanexus-sdk.s3.amazonaws.com/dnanexus-upload-agent-1.5.33-linux.tar.gz -O - |\
tar -xzf -
Install the Upload Agent on OS X as follows:
To install the Upload Agent on Windows:
The DNAnexus Download Agent is a command-line tool for downloading large numbers of files from the DNAnexus Platform to a local environment. It is designed to ensure the success of downloads that can take a long time to complete.
A list of Download Agent releases is available in Releases section of the Download Agent Github repository. The Download Agent Docker repository provides access to experimental builds corresponding to commits to the master branch.
dxCompiler is used to generate a DNAnexus workflow from a workflow written in Workflow Description Language (WDL). dxCompiler is a JAR file that can be run with Java 8 or later, and can be downloaded from the releases section of the dxCompiler Github repository. dxCompiler is also released as a public Docker container that includes the Java dependency. The dxCompiler README documents setup instructions and sample workflows.
Before using dxCompiler, ensure that you do the following:
- Install the
- Initialize the
dxcommand-line tool via the command