Synapse Python Client

4.12.0 verified Sat May 09 auth: no python

The official Python client for Synapse, a collaborative open-source research platform by Sage Bionetworks. Current version 4.12.0 (requires Python >=3.10, <3.15). Enables programmatic access to data storage, analysis tracking, and collaboration features. Released approximately monthly with breaking changes introduced in major versions (e.g., v4.x dropped Python 3.8 support and shifted to object-oriented models).

pip install synapseclient

Common errors

error ImportError: cannot import name 'Synapse' from 'synapseclient' ↓

cause Wrong import path: using `from synapseclient import Synapse` works but if the package is not installed or old version.

fix

Ensure recent version: pip install --upgrade synapseclient. Check Python version; if using Python 3.8, upgrade to >=3.10.

error synapseclient.exceptions.SynapseNoCredentialsError: No credentials provided ↓

cause `syn.login()` called without arguments and no cached credentials found.

fix

Set environment variables SYNAPSE_EMAIL and SYNAPSE_PASSWORD or use a .synapseConfig file.

error synapseclient.exceptions.SynapseHTTPError: 403 Forbidden - You do not have permission to access this resource ↓

cause User token lacks access to the specified Synapse entity (project/file) or wrong permissions.

fix

Verify you have appropriate download/upload permissions. Use syn.onweb() to open in browser or ask admin to grant access.

error TypeError: Table.query_sync() got an unexpected keyword argument 'includeEntityEtag' ↓

cause Using an old API call that changed between v4.x versions.

fix

Refer to updated Table API: use syn.tableQuery('SELECT * FROM syn...') or consult migration docs for changes in 4.11+.

Warnings

breaking Python 3.8 support dropped in v4.4.2. Must use Python >=3.10,<3.15. ↓

fix Upgrade Python to 3.10-3.14. Use virtual environment.

breaking Many class-based models (e.g., Entity, Evaluation, Submission) have been replaced by object-oriented counterparts in v4.10+ (e.g., `Evaluation -> EvaluationV2`). Old imports may fail. ↓

fix Check migration guide: https://python-docs.synapse.org/en/stable/reference/migration-v4.html

deprecated `synapseclient.entity` submodule is deprecated; import Entity classes from top-level `synapseclient` instead. ↓

fix Use `from synapseclient import File, Folder, Project` instead of `from synapseclient.entity import File`.

gotcha Authentication via `syn.login()` without arguments tries cached credentials; if none, it prompts interactively. In CI, always provide credentials explicitly. ↓

fix Supply email/password or authToken as arguments: `syn.login(email=..., password=...)` or use `SYNAPSE_AUTH_TOKEN` environment variable.

gotcha When storing large files with `syn.store()`, the method returns immediately but upload continues asynchronously. Use `syn.waitForAsync()` or check `file_entity['_status']` if synchronous behavior needed. ↓

fix Call `syn.store(file_entity, forceVersion=False)` and monitor progress with callbacks or after invocation.

Install

pip install synapseclient[pandas]

Imports

Synapse
wrong
```
import synapseclient
```
correct
```
from synapseclient import Synapse
```
Direct import only exposes module namespace; must import Synapse class explicitly.
File
wrong
```
from synapseclient.entity import File
```
correct
```
from synapseclient import File
```
Entity submodules like synapseclient.entity are deprecated in favor of top-level imports.
Schema
wrong
```
from synapseclient.models import Schema
```
correct
```
from synapseclient import Schema
```
Schema was moved to top-level in v4.x; old path no longer exists.

Quickstart

Authenticate, upload a file, and run a table query. Replace 'syn12345678' with a real Synapse ID.

import os
from synapseclient import Synapse, File

# Authenticate using personal access token or credentials
syn = Synapse()
syn.login(email=os.environ.get('SYNAPSE_EMAIL', ''), password=os.environ.get('SYNAPSE_PASSWORD', ''), rememberMe=True)

# Upload a file
file_entity = File('example.txt', parent='syn12345678')
file_entity = syn.store(file_entity)
print(f'Stored file with ID: {file_entity.id}')

# Query for data
results = syn.tableQuery('SELECT * FROM syn12345678')
df = results.asDataFrame()