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. It also holds a Zarr v3 copy of the project for copick 2.0 (the *_v3 paths), which copick 1.x does not read.

To test with the example dataset:

Download and unpack the example dataset

Add the location of the sample_project-directory in the unpacked dataset to filesystem_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
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())
arrays = list(group.arrays())
_, array = arrays[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 format
fix: resolve memory leak in zarr loading
docs: update installation instructions
test: 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.

Metadata

Release files for copick 1.28.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for copick 1.28.1
File	Size	Uploaded
copick-1.28.1.tar.gz	47.9 MB	Oct 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for copick 1.28.1
File	Interpreter	ABI	Platform	Reset
copick-1.28.1-py3-none-any.whl 275.9 kB Oct 6, 2026	Python 3	none	any	Details

Total release size: 48.2 MB

Release files / copick-1.28.1.tar.gz

Download URL	copick-1.28.1.tar.gz
Size	47.9 MB
Tags	Source
SHA-256 checksum How to use checksums	`f072fc882069a037477582994b29e2de0c093132f8a67c155f4555c4723fd70f`
BLAKE2b-256 checksum How to use checksums	`d8988476d11507582d68190b2f2d32ba7efdcb1dec616f26aed9dd2c2892c1c8`
Upload date	Oct 6, 2026
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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/copick/copick
Publishing commit: github.com/copick/copick/tree/4b158119b7ba42065c2a48ea43ad435abea80bd4

Workflow

Publishing configuration: github.com/copick/copick/blob/4b158119b7ba42065c2a48ea43ad435abea80bd4/.github/workflows/release-please.yml
Publishing logs: github.com/copick/copick/actions/runs/37434287690/attempts/1

Artifact

Subject: copick-1.28.1.tar.gz
SHA-256 checksum: f072fc882069a037477582994b29e2de0c093132f8a67c155f4555c4723fd70f Verifying attestations

Release files / copick-1.28.1-py3-none-any.whl

Download URL	copick-1.28.1-py3-none-any.whl
Size	275.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`331c4e8e094f2a5a2b53e66b38338854b355eab612edd905a1418ced73bd292c`
BLAKE2b-256 checksum How to use checksums	`8a564b2258f34fc91d2bb4005e13b83fcdd5e102e553648845d93d1227dd8077`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/copick/copick
Publishing commit: github.com/copick/copick/tree/4b158119b7ba42065c2a48ea43ad435abea80bd4

Workflow

Publishing configuration: github.com/copick/copick/blob/4b158119b7ba42065c2a48ea43ad435abea80bd4/.github/workflows/release-please.yml
Publishing logs: github.com/copick/copick/actions/runs/37434287690/attempts/1

Artifact

Subject: copick-1.28.1-py3-none-any.whl
SHA-256 checksum: 331c4e8e094f2a5a2b53e66b38338854b355eab612edd905a1418ced73bd292c Verifying attestations