Introduction

Creating high-quality labeled datasets is often the most time-consuming bottleneck in any machine learning pipeline. For developers and data scientists struggling with the manual effort of tagging raw text, Doccano is a streamlined, open-source solution designed to accelerate this process. With its intuitive web interface and support for common NLP tasks, Doccano replaces the need for expensive proprietary labeling software or cumbersome manual spreadsheets, allowing teams to build training-ready datasets in hours rather than weeks.

What Is Doccano?

Doccano is an open-source text annotation tool that provides a collaborative environment for humans to label data for machine learning practitioners. It is primarily designed for Natural Language Processing (NLP) tasks, focusing on text classification, sequence labeling (such as Named Entity Recognition), and sequence-to-sequence tasks (such as text summarization or translation).

Built with a Python-based backend (Django) and a modern frontend, Doccano is licensed under the MIT License, ensuring it remains free and customizable for any organization. It allows users to create projects, upload raw text data, and assign labels using a simple, browser-based GUI, which can be self-hosted on local machines or cloud servers.

Why Doccano Matters

The gap between raw data and a trained model is the “labeled data gap.” Most AI teams spend over 80% of their time on data preparation and labeling. Doccano fills this gap by providing a professional-grade annotation interface that is significantly faster than using generic text editors or spreadsheets. By centralizing the annotation process, it eliminates the versioning conflicts and data corruption common in shared documents.

For teams that cannot use cloud-based SaaS tools due to data privacy or compliance requirements, Doccano’s self-hosted nature is a critical advantage. It ensures that sensitive training data never leaves the organization’s own infrastructure, making it an ideal choice for healthcare, finance, or legal sectors where data sovereignty is non-negotiable.

Furthermore, the project’s open-source nature allows developers to extend its functionality via a RESTful API, meaning the labeling process can be integrated directly into a larger automated ML pipeline, enabling a more iterative approach to data curation.

Key Features

• Collaborative Annotation: Multiple users can work on the same project simultaneously, allowing teams to distribute the labeling workload and improve consistency through shared labels.
• Multi-Language Support: The tool is designed to handle text in various languages, making it suitable for global NLP projects and multilingual datasets.
• RESTful API: A comprehensive API allows for the programmatic upload of documents, project management, and the export of annotated data, facilitating seamless integration with Python scripts.
• Sequence Labeling: Specialized tools for Named Entity Recognition (NER), allowing users to highlight spans of text and assign them to specific categories (e.g., Person, Organization, Location).
• Text Classification: A simple interface for assigning a single label or multiple labels to an entire document for sentiment analysis or topic categorization.
• Sequence-to-Sequence: Support for tasks like translation or summarization where the user provides a target text for a source text.
• Mobile and Emoji Support: The interface is responsive and supports emojis, ensuring that data from social media or chat logs is annotated accurately.
• Dark Theme: A built-in dark mode to reduce eye strain for annotators working long hours on large datasets.

How Doccano Compares

When choosing an annotation tool, the decision usually comes down to a trade-off between simplicity, modality support, and cost. Doccano is optimized for text-only workflows where speed and ease of setup are the primary goals.

Doccano is the best choice for teams that need a clean, lightweight tool specifically for text. While Label Studio is more powerful in terms of modality (supporting images and audio), it can feel bloated for a simple NER project. Prodigy, while excellent for active learning, is a paid commercial product. Doccano provides the most straightforward path from raw text to labeled JSON/CSV files without any licensing fees.

Getting Started: Installation

Doccano offers multiple installation paths depending on your environment and required database backend.

Install with pip

Requires Python 3.8+. Run the following commands to install and initialize the server:

pip install doccano

doccano init
doccano createuser --username admin --password pass
doccano webserver --port 8000

# In a separate terminal, run the task queue
doccano task

Install with Docker

This is the recommended method for most users to avoid dependency conflicts. Run the following to create and start the container:

docker pull doccano/doccano

docker container create --name doccano \
  -e "ADMIN_USERNAME=admin" \
  -e "ADMIN_EMAIL=admin@example.com" \
  -e "ADMIN_PASSWORD=password" \
  -v doccano-db:/data \
  -p 8000:8000 doccano/doccano

docker container start doccano

Install with Docker Compose

For production-like environments, use Docker Compose to manage the backend and database separately. You can find the docker-compose.yml file in the official repository.

How to Use Doccano

Once the server is running and you have accessed the dashboard at http://localhost:8000, the workflow follows a simple four-step process.

First, create a project. Select the project type (Text Classification, Sequence Labeling, or Sequence-to-Sequence). Define the labels you want to use (e.g., for NER, you might create labels like “PERSON” and “ORG”).

Next, upload your data. You can upload files in JSONL or CSV format. Doccano will import these documents into the database, and they are now ready for the annotation queue.

Then, annotate. Assign annotators to the project. Annotators can now select text spans and assign labels to them. The system tracks which documents have been annotated and their progress.

Finally, export. Once the project is complete, you can export the annotated data in various formats (JSONL, CSV) to be used directly in your training scripts for models like BERT or spaCy.

Code Examples

Doccano’s REST API allows you to automate the data pipeline. Here is how you can interact with the project using Python.

Programmatic Project Creation

You can create a project via the API to avoid manual setup in the GUI.

import requests

API_URL = "http://localhost:8000/api/projects/"
TOKEN = "your_api_token"

headers = {"Authorization": f"Token {TOKEN}"}

project_data = {
    "name": "Sentiment Analysis Project",
    "license": "MIT",
    "description": "Labeling movie reviews for sentiment",
    "type": "textclassification"
}

response = requests.post(API_URL, json=project_data, headers=headers)
print(response.json())

Exporting Annotated Data

The API allows you to retrieve the annotated documents for a specific project.

import requests

PROJECT_ID = "1"
API_URL = f"http://localhost:8000/api/projects/{PROJECT_ID}/export/"
TOKEN = "your_api_token"

headers = {"Authorization": f"Token {TOKEN}"}

response = requests.get(API_URL, headers=headers)

# The response is usually a JSONL file containing the text and the label
with open("annotated_data.jsonl", "w") as f:
    for line in response.text.split("\n"):
        f.write(line)

Advanced Configuration

For production deployments, Doccano requires specific environment variables to ensure security and database stability. If you are using PostgreSQL instead of the default SQLite, you must set the DATABASE_URL variable.

# Example PostgreSQL connection string
DATABASE_URL="postgres://user:password@host:port/dbname?sslmode=disable"

# To prevent CSRF errors in production
CSRF_TRUSTED_ORIGINS="http://yourdomain.com"

# To change the default port
PORT=8000

Setting CSRF_TRUSTED_ORIGINS is critical when deploying Doccano behind a reverse proxy like Nginx, as it prevents the API from rejecting requests from your domain name.

Real-World Use Cases

Doccano is most effective when the project requires high-precision human labeling for specific NLP domains.

• Medical Entity Extraction: A healthcare provider can use Doccano to label clinical notes for Named Entity Recognition (NER), tagging terms like “Symptom,” “Medication,” and “Dosage” to train a model that automatically extracts patient data.
• Customer Support Ticket Classification: A company can upload thousands of support tickets to Doccano, have a team of agents label them by “Urgency” and “Product Category,” and then train a classifier to automatically route tickets to the correct department.
• SBOM Analysis: Security researchers can use Doccano to label software bill of materials (SBOM) logs to identify patterns of vulnerable dependencies, training a model to detect anomalies in dependency trees.
• Legal Document Summarization: A legal firm can use the Sequence-to-Sequence feature to create a pair of “Original Contract” and “Summary” to train a fine-tuned LLM for legal summarization.

Contributing to Doccano

Doccano is an open-source project that welcomes contributions from the machine learning community. If you want to get involved, you can start by reporting bugs via GitHub Issues or suggesting new features in the discussions tab.

The project follows a standard GitHub flow: fork the repository, create a feature branch, and submit a pull request. For those looking to contribute to the backend, the project is built on Django, while the frontend is based on Node.js. Developers should refer to the CONTRIBUTING.md file in the root of the repository for specific coding standards and setup instructions for development.

Community and Support

Doccano is primarily supported through its official GitHub repository and documentation site. The most active community discussions happen in the GitHub Issues and Discussions sections, where users share configuration tips and deployment strategies.

For detailed setup guides and tutorials, users should visit the official documentation at Doccano Documentation. The project is maintained by a global community of open-source contributors, ensuring that the tool remains updated for modern Python environments.

Conclusion

Doccano is the ideal choice for teams that need a lightweight, self-hosted, and free tool for text annotation. While it is not as feature-rich as enterprise platforms like Label Studio or as specialized as Prodigy, the simplicity is its greatest strength. It allows a team to go from zero to a labeled dataset without the need for complex configuration or expensive licenses.

If your project is primarily text-based and you prioritize data privacy and ease of setup, Doccano is the right tool for the job. Star the repo, try the quickstart, and join the community to help build better training data for your AI models.

Resources

• Doccano GitHub Repository
• Official Doccano Documentation
• Doccano Tutorial Guide