DNAnexus Documentation
APIDownloadsIndex of dx CommandsLegal
  • Overview
  • Getting Started
    • DNAnexus Essentials
    • Key Concepts
      • Projects
      • Organizations
      • Apps and Workflows
    • User Interface Quickstart
    • Command Line Quickstart
    • Developer Quickstart
    • Developer Tutorials
      • Bash
        • Bash Helpers
        • Distributed by Chr (sh)
        • Distributed by Region (sh)
        • SAMtools count
        • TensorBoard Example Web App
        • Git Dependency
        • Mkfifo and dx cat
        • Parallel by Region (sh)
        • Parallel xargs by Chr
        • Precompiled Binary
        • R Shiny Example Web App
      • Python
        • Dash Example Web App
        • Distributed by Region (py)
        • Parallel by Chr (py)
        • Parallel by Region (py)
        • Pysam
      • Web App(let) Tutorials
        • Dash Example Web App
        • TensorBoard Example Web App
      • Concurrent Computing Tutorials
        • Distributed
          • Distributed by Region (sh)
          • Distributed by Chr (sh)
          • Distributed by Region (py)
        • Parallel
          • Parallel by Chr (py)
          • Parallel by Region (py)
          • Parallel by Region (sh)
          • Parallel xargs by Chr
  • User
    • Login and Logout
    • Projects
      • Project Navigation
      • Path Resolution
    • Running Apps and Workflows
      • Running Apps and Applets
      • Running Workflows
      • Running Nextflow Pipelines
      • Running Batch Jobs
      • Monitoring Executions
      • Job Notifications
      • Job Lifecycle
      • Executions and Time Limits
      • Executions and Cost and Spending Limits
      • Smart Reuse (Job Reuse)
      • Apps and Workflows Glossary
      • Tools List
    • Cohort Browser
      • Chart Types
        • Row Chart
        • Histogram
        • Box Plot
        • List View
        • Grouped Box Plot
        • Stacked Row Chart
        • Scatter Plot
        • Kaplan-Meier Survival Curve
      • Locus Details Page
    • Using DXJupyterLab
      • DXJupyterLab Quickstart
      • Running DXJupyterLab
        • FreeSurfer in DXJupyterLab
      • Spark Cluster-Enabled DXJupyterLab
        • Exploring and Querying Datasets
      • Stata in DXJupyterLab
      • Running Older Versions of DXJupyterLab
      • DXJupyterLab Reference
    • Using Spark
      • Apollo Apps
      • Connect to Thrift
      • Example Applications
        • CSV Loader
        • SQL Runner
        • VCF Loader
      • VCF Preprocessing
    • Environment Variables
    • Objects
      • Describing Data Objects
      • Searching Data Objects
      • Visualizing Data
      • Filtering Objects and Jobs
      • Archiving Files
      • Relational Database Clusters
      • Symlinks
      • Uploading and Downloading Files
        • Small File Sets
          • dx upload
          • dx download
        • Batch
          • Upload Agent
          • Download Agent
    • Platform IDs
    • Organization Member Guide
    • Index of dx commands
  • Developer
    • Developing Portable Pipelines
      • dxCompiler
    • Cloud Workstation
    • Apps
      • Introduction to Building Apps
      • App Build Process
      • Advanced Applet Tutorial
      • Bash Apps
      • Python Apps
      • Spark Apps
        • Table Exporter
        • DX Spark Submit Utility
      • HTTPS Apps
        • Isolated Browsing for HTTPS Apps
      • Transitioning from Applets to Apps
      • Third Party and Community Apps
        • Community App Guidelines
        • Third Party App Style Guide
        • Third Party App Publishing Checklist
      • App Metadata
      • App Permissions
      • App Execution Environment
        • Connecting to Jobs
      • Dependency Management
        • Asset Build Process
        • Docker Images
        • Python package installation in Ubuntu 24.04 AEE
      • Job Identity Tokens for Access to Clouds and Third-Party Services
      • Enabling Web Application Users to Log In with DNAnexus Credentials
      • Types of Errors
    • Workflows
      • Importing Workflows
      • Introduction to Building Workflows
      • Building and Running Workflows
      • Workflow Build Process
      • Versioning and Publishing Global Workflows
      • Workflow Metadata
    • Ingesting Data
      • Molecular Expression Assay Loader
        • Common Errors
        • Example Usage
        • Example Input
      • Data Model Loader
        • Data Ingestion Key Steps
        • Ingestion Data Types
        • Data Files Used by the Data Model Loader
        • Troubleshooting
      • Dataset Extender
        • Using Dataset Extender
    • Dataset Management
      • Rebase Cohorts and Dashboards
      • Assay Dataset Merger
      • Clinical Dataset Merger
    • Apollo Datasets
      • Dataset Versions
      • Cohorts
    • Creating Custom Viewers
    • Client Libraries
      • Support for Python 3
    • Walkthroughs
      • Creating a Mixed Phenotypic Assay Dataset
      • Guide for Ingesting a Simple Four Table Dataset
    • DNAnexus API
      • Entity IDs
      • Protocols
      • Authentication
      • Regions
      • Nonces
      • Users
      • Organizations
      • OIDC Clients
      • Data Containers
        • Folders and Deletion
        • Cloning
        • Project API Methods
        • Project Permissions and Sharing
      • Data Object Lifecycle
        • Types
        • Object Details
        • Visibility
      • Data Object Metadata
        • Name
        • Properties
        • Tags
      • Data Object Classes
        • Records
        • Files
        • Databases
        • Drives
        • DBClusters
      • Running Analyses
        • I/O and Run Specifications
        • Instance Types
        • Job Input and Output
        • Applets and Entry Points
        • Apps
        • Workflows and Analyses
        • Global Workflows
        • Containers for Execution
      • Search
      • System Methods
      • Directory of API Methods
      • DNAnexus Service Limits
  • Administrator
    • Billing
    • Org Management
    • Single Sign-On
    • Audit Trail
    • Integrating with External Services
    • Portal Setup
    • GxP
      • Controlled Tool Access (allowed executables)
  • Science Corner
    • Scientific Guides
      • Somatic Small Variant and CNV Discovery Workflow Walkthrough
      • SAIGE GWAS Walkthrough
      • LocusZoom DNAnexus App
      • Human Reference Genomes
    • Using Hail to Analyze Genomic Data
    • Open-Source Tools by DNAnexus Scientists
    • Using IGV Locally with DNAnexus
  • Downloads
  • FAQs
    • EOL Documentation
      • Python 3 Support and Python 2 End of Life (EOL)
    • Automating Analysis Workflow
    • Backups of Customer Data
    • Developing Apps and Applets
    • Importing Data
    • Platform Uptime
    • Legal and Compliance
    • Sharing and Collaboration
    • Product Version Numbering
  • Release Notes
  • Technical Support
  • Legal
Powered by GitBook

Copyright 2025 DNAnexus

On this page
  • DNAnexus Platform SDK
  • Installing the Python SDK and Command Line Tools
  • Building from Source
  • Using the SDK
  • Upload Agent
  • Features
  • Installing the Upload Agent
  • Using the Upload Agent
  • Download Agent
  • Features and Usage
  • Downloads
  • dxCompiler
  • Installing dxCompiler

Was this helpful?

Export as PDF

Downloads

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

Last updated 5 months ago

Was this helpful?

DNAnexus Platform SDK

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

The SDK is released under the . 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 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

Installation

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

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 

Enabling Tab Completion

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 .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 dxpypackage after installing it using pip3, enter the command:

pip3 install --upgrade dxpy

Troubleshooting

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

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

export PYTHONIOENCODING=UTF-8

On Windows, Windows 10 and later versions are supported.

Building from Source

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.

Learn More

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.

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, OS X, 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 OS X

Install the Upload Agent on OS X 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. Unzip the file using your favorite utility

  2. Run ua.exe

Using 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

Downloads

dxCompiler

Installing dxCompiler

To set up and use dxCompiler, follow these steps:

  • Run dx login to log into DNAnexus

  • Select a dxCompiler execution method:

    • Using a JAR file

      • Install Java SDK 8 or 11

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

    • Using a Docker container

      • Install the Docker CLI

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

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. if you are using Windows and have trouble connecting through a proxy.

The will get you started on accessing the platform via the command-line interface.

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

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

Download or

.

For a detailed description of Download Agent features and usage, please review the .

A list of Download Agent releases is available in . The provides access to experimental builds corresponding to commits to the master branch.

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

the dx DNAnexus command-line tool

Download the dxCompiler JAR file from the of the dxCompiler Github repository

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

Use script to invoke dxCompiler with the built Docker container image

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

dx-toolkit Github repository
Contact DNAnexus Support
Command Line Quickstart
Developer
DNAnexus Upload Agent 1.5.33 Installer.exe
dnanexus-upload-agent-1.5.33-windows.zip
See this page for full details on the features and usage of the Upload Agent
README file in the Download Agent Github repository
Releases section of the Download Agent Github repository
Download Agent Docker repository
Workflow Description Language (WDL)
JAR file
releases section
instructions
docker_run.sh
dxCompiler Github README
Apache v2.0 license
Python 3.
PyPI
pip3
dxpy
Upload Agent
create an authentication token
Set up