This release is a pre-release and may not be stable for production use.
copick
copick is a cross-platform, storage-agnostic and server-less dataset API for cryoET datasets. Access to the data is provided through an object-oriented API that abstracts away the underlying storage using the fsspec-family of libraries.
Why copick?
- storage-agnostic: Access data on local or shared filesystems, via SSH or on the cloud with the same API. No need for your own boilerplate!
- cloud-ready: Access image data quickly and in parallel thanks to multiscale OME-Zarr!
- server-less: No need for a dedicated server or database to access your data, just point copick to your data and go!
- cross-platform: copick works on any platform that supports Python. Compute on Linux, visualize on Windows or Mac, all with the same dataset API!
- ecosystem: Using the copick API allows visualizing and curating data in ChimeraX and Napari right away!
Documentation
For more information, see the documentation.
Installation
copick can be installed using pip. Using the all extra installs necessary requirements for all tested filesystem
implementations from the fsspec family (local, s3fs, smb, sshfs). A separate smb extra is available.
pip install "copick[all]"
Example dataset
An example dataset can be obtained from Zenodo. The migration-test archive contains both the legacy Zarr v2 project and its Zarr v3 twin, so it is larger than the earlier single-format example.
To test with the example dataset:
-
Download and unpack the example dataset
-
Add the location of the
sample_project-directory in the unpacked dataset tofilesystem_overlay_only.json{ "name": "test", "description": "A test project.", "version": "1.0.0", "pickable_objects": [ { "name": "proteasome", "is_particle": true, "pdb_id": "3J9I", "label": 1, "color": [255, 0, 0, 255], "radius": 60, "map_threshold": 0.0418 }, { "name": "ribosome", "is_particle": true, "pdb_id": "7P6Z", "label": 2, "color": [0, 255, 0, 255], "radius": 150, "map_threshold": 0.037 }, { "name": "membrane", "is_particle": false, "label": 3, "color": [0, 0, 0, 255] } ], // Change this path to the location of sample_project "overlay_root": "local:///PATH/TO/EXTRACTED/PROJECT/", "overlay_fs_args": { "auto_mkdir": true } }
-
Start copick with the configuration file
from copick.impl.filesystem import CopickRootFSSpec root = CopickRootFSSpec.from_file('path/to/filesystem_overlay_only.json')
-
Access the data using the copick API
import zarr from copick.impl.filesystem import CopickRootFSSpec from copick.util.ome import get_level_path root = CopickRootFSSpec.from_file('path/to/filesystem_overlay_only.json') # Get a run by name run = root.get_run("TS_001") # Get a tomogram by name tomogram = run.get_voxel_spacing(10).get_tomogram("wbp") # Access the data group = zarr.open(tomogram.zarr(), mode="r") # Inspect every stored array without assuming numeric names or iteration order for path, candidate in group.arrays(): print(path, candidate.shape) # Select OME pyramid levels from metadata array = group[get_level_path(group, 0)]
Contributing
We welcome contributions to copick! Here's how to get started:
Development Setup
-
Clone the repository and install with development dependencies:
git clone https://github.com/copick/copick.git cd copick pip install -e ".[dev,test]"
-
Install pre-commit hooks:
pre-commit install -
Run tests to ensure everything is working:
pytest
Code Quality
We use several tools to maintain code quality:
- Black for code formatting
- Ruff for linting and import sorting
- Pre-commit hooks to enforce standards
Before submitting a PR, ensure your code passes all checks:
black src/ tests/
ruff check --fix src/ tests/
pytest
Conventional Commits
All pull requests must use Conventional Commits for commit messages. This helps us automatically generate changelogs and determine version bumps.
Examples:
feat: add support for new tomogram formatfix: resolve memory leak in zarr loadingdocs: update installation instructionstest: add unit tests for mesh operations
Plugin System
Copick supports a plugin system that allows external Python packages to register CLI commands. Commands can be added to the main CLI or organized into groups like inference, training, evaluation, process, and convert.
See the CLI documentation for detailed plugin development instructions and the copick-plugin-demo repository for a complete example.
Code of Conduct
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.
Reporting Security Issues
If you believe you have found a security issue, please responsibly disclose by contacting us at security@chanzuckerberg.com.
Release files for copick 2.0.0a5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| copick-2.0.0a5.tar.gz | 47.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| copick-2.0.0a5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 48.2 MB
Release files / copick-2.0.0a5.tar.gz
| Download URL | copick-2.0.0a5.tar.gz |
|---|---|
| Size | 47.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
de018d823feb15f04786f142dcdcacbabbca6a474a7395c51680cf92ccbfa3f5
|
|
BLAKE2b-256 checksum How to use checksums |
17e90526e32943b9a077c38239f7e96d76877f1ae2f2f252f74fa80224eb45ca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logRelease files / copick-2.0.0a5-py3-none-any.whl
| Download URL | copick-2.0.0a5-py3-none-any.whl |
|---|---|
| Size | 285.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d19a95d5899f6c5b5259cb2f48e6a4bc1cbaf532ace39c337fa6aaac847b1974
|
|
BLAKE2b-256 checksum How to use checksums |
0719e2e5879f24fdd73a23acf834a6d21ce80e5fbbd9caf99180803f13e3060e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency log
