Registry / gcp / synapseclient

synapseclient

library4.12.0pypypi✓ verified 84d ago

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

gcp data devops

pip install synapseclient

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · SYNAPSECLIENT

synapseclient

gcppythonv4.12.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Synapse

✓ from synapseclient import Synapse

✗ import synapseclient

Direct import only exposes module namespace; must import Synapse class explicitly.

File

✓ from synapseclient import File

✗ from synapseclient.entity import File

Entity submodules like synapseclient.entity are deprecated in favor of top-level imports.

Schema

✓ from synapseclient import Schema

✗ from synapseclient.models import Schema

Schema was moved to top-level in v4.x; old path no longer exists.

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()

synapse --version

Debug

Known issues

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

affects: >=4.4.2

breakingMany 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

affects: >=4.10.0

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

affects: >=4.0.0

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

affects: all

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

affects: all

Errors

Common errors & fixes

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

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.

synapseclient.exceptions.SynapseNoCredentialsError: No credentials provided

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

fix

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

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

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.

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

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

Upgrade

Version history

4.12.0latest on PyPI · released Apr 3, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Sage-Bionetworks/synapsePythonClient ↗

packagehttps://pypi.org/project/synapseclient/ ↗

homepagehttps://www.synapse.org ↗

docshttps://python-docs.synapse.org ↗

changeloghttps://python-docs.synapse.org/en/stable/news/ ↗