Guide · Open source

How to use doccano: install, run and label text data

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

doccano is an open-source, web-based tool for annotating text, meaning you add labels to sentences or passages to create training data for machine learning. This guide walks through the three ways the README describes to run it, then shows how to create a project, upload data and label it in the browser. By the end you will have a running instance and know where to find the features that matter for a labeling project.

doccanodoccano/doccano · ★ 10.8k · MIT Install options & downloads

Quick start

1Choose an install route. Pick pip with Python 3.8 or newer, or Docker, or Docker Compose. The pip route uses SQLite by default.
2Initialize the database. Run doccano init to set up the database before starting the server.
3Create an admin user. Run doccano createuser with a username and password to get an account to log in with.
4Start the web server and task queue. Run doccano webserver --port 8000, then run doccano task in a second terminal for uploads and downloads.
5Open the browser. Go to http://127.0.0.1:8000/ and log in with the admin account you created.
6Create a project and upload data. Make a project, upload your text and start labeling it in the browser.

What doccano is and which tasks it supports

doccano is an open-source text annotation tool for humans. It provides annotation features for text classification, sequence labeling and sequence-to-sequence tasks. The README gives examples such as sentiment analysis, named entity recognition and text summarization.

Text classification: assign labels to whole texts
Sequence labeling: for example named entity recognition
Sequence-to-sequence: for example text summarization

Install doccano with pip

The pip route requires Python 3.8 or newer. By default doccano uses SQLite 3 as its database. Install it, then initialize the database, create an admin user and start the web server.

If you want PostgreSQL instead, install the extra dependencies and set the DATABASE_URL environment variable with your PostgreSQL credentials.

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

Start the task queue for file uploads and downloads

The web server alone is not enough for file handling. The README says to run a task queue in a second terminal, which handles file upload and download. Then open http://127.0.0.1:8000/ in your browser.

doccano task

Run doccano with Docker instead

The Docker route creates a container once and then starts it. Set the admin credentials with environment variables and mount a volume so data persists. The README notes that data created in the container will persist across restarts. Go to http://127.0.0.1:8000/ when it is running.

To use the latest features, the README says to pull the nightly tag. Replace the example admin values with your own before using this in a real setting.

Stop the container with the command shown below
Data persists across restarts because of the mounted volume

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
docker container stop doccano -t 5

Run doccano with Docker Compose

The Docker Compose route requires Git. Clone the repository, create an .env file with admin, RabbitMQ and database settings, then run the production compose file. The README says to access http://127.0.0.1/ afterwards. Windows users should configure Git line endings as shown, or they may see status code 127 errors.

Copy the variable format from docker/.env.example in the repository
Set ADMIN_USERNAME, ADMIN_PASSWORD and ADMIN_EMAIL
Set RABBITMQ_DEFAULT_USER, RABBITMQ_DEFAULT_PASS, POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DB

git clone https://github.com/doccano/doccano.git
cd doccano
docker-compose -f docker/docker-compose.prod.yml --env-file .env up

Create a project, upload data and label it

Once you are logged in, create a project, upload your text and start annotating. The README describes this as the core workflow: create a project, upload data and label it in the browser. Collaborative annotation is listed as a feature, so several people can work in one shared project.

For user management, the README's FAQ links cover how to create a user, how to add a user to your project and how to change the password. Those answers live in the online documentation.

Create a project for your labeling task
Upload your text data
Label sentences or passages in the browser
Add other users to the project to annotate together

What people use it for

Building a named entity recognition dataset from raw text
Creating sentiment analysis labels for a classifier
Preparing text summarization pairs for sequence-to-sequence training
Letting a small team label one shared text dataset together
Automating labeling steps through the RESTful API

Frequently asked questions

Is doccano free to use?

doccano is released under the MIT licence, as stated in the project's details. The README describes it as open source and you run it yourself. The source does not list any prices or paid tiers.

What are the requirements to install doccano?

The README lists Python 3.8 or newer for the pip route. Docker is needed only for the Docker routes. By default doccano uses SQLite 3, and PostgreSQL is optional.

How do I install doccano?

Run pip install doccano, then doccano init, doccano createuser and doccano webserver --port 8000. Start doccano task in another terminal and open http://127.0.0.1:8000/.

Can doccano label images or audio?

No. The README only describes text annotation, so it does not cover images, audio or video.

How does doccano compare to Label Studio, Prodigy, brat or INCEpTION?

Label Studio, Prodigy, brat and INCEpTION are comparable projects. This guide does not benchmark them, so compare the features you need, such as the task types and the RESTful API, directly.

Is there a hosted version of doccano?

The README covers self-hosting options and a demo at doccano.herokuapp.com. It does not describe a fully managed hosted service.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

doccano suits machine learning teams, researchers and small groups who need to label text together and want to self-host it under an MIT licence. If you need to label images, audio or video, want a fully managed hosted service, or need guaranteed enterprise support, pick a different tool.

Install options & downloads