APIDownloadsIndex of dx CommandsLegal

Downloads

Download, install, and get started using the DNAnexus Platform SDK, the DNAnexus upload and download agents, and dxCompiler.

DNAnexus Platform SDK

The DNAnexus Platform SDK - also called dx-toolkit - includes the dx command-line client. It provides 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.

The SDK is released under the Apache v2.0 license. This SDK does not collect any user identifiable information.

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.

Installing the Python SDK and Command Line Tools

Before You Begin

Before installing the Python SDK and command line tools, ensure that you are running Python 3.

Installation

The Python SDK components - dxpy bindings and command line tools, including dx - are distributed through PyPI. Use pip3 to download and install the dxpy package:

pip3 install dxpy

If you see a warning similar to the one below, 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

Enabling Tab Completion

If you're using Z shell (zsh), which is included in recent versions of macOS, enable tab completion by entering the following command (or add it to your .zshrc):

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 .bashrc):

eval "$(register-python-argcomplete dx|sed 's/-o default//')"

Upgrading dxpy

To upgrade the dxpy package after installing it using pip3, enter the following command:

pip3 install --upgrade dxpy

Troubleshooting

To avoid character set problems when running the dx command, set the PYTHONIOENCODING environment variable to UTF-8 as follows:

export PYTHONIOENCODING=UTF-8

If you're using the macOS 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 dxpy.

On Windows, the DNAnexus SDK requires Windows 10 and later. If you encounter the error ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1108) error when running dx commands, such as dx head file-xxx, install python-certifi-win32 using pip install python-certifi-win32.

Building from Source

See the Readme.md file in the dx-toolkit GitHub repository for information on build-time dependencies, Java, C++ and R bindings and additional installation instructions.

Using the SDK

Using a Proxy

To direct dx-toolkit to a proxy, set the HTTP_PROXY or HTTPS_PROXY environment variable to an appropriate value:

export HTTP_PROXY=hostname:port

TLS Settings

By default, dx-toolkit uses certificates installed on your system to create secure connections. If your system requires an additional TLS certificate, and dx-toolkit doesn'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_CERT environment 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 DX_CA_CERT=NOVERIFY.

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.

Learn More

  • The Command Line Quickstart helps you get started on accessing the platform via the command-line interface.

  • The Developer section contains comprehensive information on how to use the SDK to interact with, and write your own applications for the Platform.

Java, R, and C++ SDKs

See the dx-toolkit GitHub repository for the Java, R, and C++ SDKs.

Upload Agent

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.

Using the Upload Agent requires an authentication token. Create an authentication token before proceeding.

Features

  • 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.

Installing the Upload Agent

The Upload Agent is available pre-built for 64-bit Linux, macOS, and Windows.

Installation on 64-bit Linux

Install the Upload Agent on 64-bit Linux as follows:

wget \
  https://dnanexus-sdk.s3.amazonaws.com/dnanexus-upload-agent-1.5.33-linux.tar.gz -O - |\
  tar -xzf -
cd dnanexus-upload-agent-*-linux
./ua

Installation on macOS

Install the Upload Agent on macOS as follows:

curl \
  https://dnanexus-sdk.s3.amazonaws.com/dnanexus-upload-agent-1.5.33-osx.zip \
  -o ua.zip
unzip ua.zip
cd dnanexus-upload-agent-*-osx
./ua

Installation on Windows

To install the Upload Agent on Windows:

  1. Download DNAnexus Upload Agent 1.5.33 Installer.exe or dnanexus-upload-agent-1.5.33-windows.zip

  2. Unzip the file using your favorite utility

  3. Run ua.exe

Using the Upload Agent

See this page for full details on the features and usage of the Upload Agent.

Download Agent

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.

Features and Usage

For a detailed description of Download Agent features and usage, review the README file in the Download Agent GitHub repository.

Downloads

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

dxCompiler is a tool for building a DNAnexus workflows from a workflows written in Workflow Description Language (WDL). It is distributed as a JAR file that can be executed using Java (version 8 or 11).

Installing dxCompiler

To set up and use dxCompiler, follow these steps:

  • Set up the dx DNAnexus command-line tool

  • Run dx login to log into DNAnexus

  • Select a dxCompiler execution method:

    • Using a JAR file

      • Download the dxCompiler JAR file from the releases section of the dxCompiler GitHub repository

      • Install Java SDK 8 or 11

      • Run dxCompiler using java -jar dxCompiler.jar compile workflow_file.wdl

    • Using a Docker container

      • Build a Docker image with dxCompiler and Java version 8 or 11 following the instructions in the dxCompiler GitHub repository

      • Install the Docker CLI

      • Use docker_run.sh script to invoke dxCompiler with the built Docker container image

More detailed setup instructions and sample WDL workflows can be found in the dxCompiler GitHub README.

Last updated

Was this helpful?