Skip to main content

​
Overview

This quickstart guide will walk you through:
  1. Creating an account or setting up self-hosted
  2. Creating your first project
  3. Syncing with QField mobile app
  4. Collecting field data
  5. Syncing changes back
By the end, you’ll have a complete field data collection workflow running.

​
Prerequisites

Before you begin, make sure you have:
  • QGIS Desktop (3.22 or later) with the QFieldSync plugin installed
  • QField mobile app installed on your Android or iOS device
  • A QGIS project ready to use in the field
  1. Open QGIS Desktop
  2. Go to Plugins → Manage and Install Plugins
  3. Search for “QFieldSync”
  4. Click Install Plugin

​
Step 1: Create Your Account

Use the official hosted service at app.qfield.cloud:
  1. Navigate to app.qfield.cloud
  2. Click Sign Up
  3. Enter your email and create a password
  4. Verify your email address
  5. Log in to your account
The hosted service includes:
  • Automatic updates and maintenance
  • 100 MB free storage
  • Built-in support
  • No infrastructure management

​
Step 2: Get Your API Token

You’ll need an API token to authenticate QFieldSync and QField mobile.
1

Log in to QFieldCloud

Navigate to your QFieldCloud instance (app.qfield.cloud or your self-hosted URL) and log in.
2

Generate API Token

  1. Click on your profile icon in the top right
  2. Select Account Settings
  3. Go to the API Tokens section
  4. Click Create New Token
  5. Give your token a descriptive name (e.g., “QGIS Desktop”)
  6. Copy the token - you won’t be able to see it again
Store your API token securely. It provides full access to your account and projects.
Alternatively, generate a token via API: 
curl -X POST https://app.qfield.cloud/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "password": "your-password"
  }'
Response: 
{
  "token": "your-api-token-here",
  "user": {
    "username": "your-username",
    "email": "[email protected]"
  }
}

​
Step 3: Configure QFieldSync

Connect QGIS to your QFieldCloud instance.
1

Open QFieldSync in QGIS

In QGIS Desktop, go to Plugins → QFieldSync
2

Configure Cloud Connection

  1. Click the QFieldCloud tab
  2. Enter your QFieldCloud URL:
    • Hosted: https://app.qfield.cloud
    • Self-hosted: Your instance URL (e.g., https://qfc.example.com)
  3. Enter your API token
  4. Click Test Connection to verify
Your connection settings are saved locally in QGIS.

​
Step 4: Create and Upload Your Project

1

Prepare Your QGIS Project

Open your QGIS project and ensure:
  • All layers are properly configured
  • Forms are set up for field data collection
  • Any required attachments or symbols are included
  • The project is saved
Use relative paths for data sources to ensure portability.
2

Create Cloud Project

In the QFieldSync panel:
  1. Click Create Cloud Project
  2. Enter a project name (e.g., “Field Survey 2024”)
  3. Choose project visibility:
    • Private: Only you and collaborators can access
    • Public: Anyone can view (but not edit)
  4. Click Create
3

Upload Project Files

  1. Click Synchronize to upload your project
  2. QFieldSync will:
    • Package your QGIS project for mobile use
    • Upload all layers and data
    • Process symbology and forms
    • Create a mobile-optimized package
This may take a few minutes depending on your project size.
  • QGIS project file (.qgs or .qgz)
  • All data layers (GeoPackage, Shapefiles, etc.)
  • Symbology (SVG symbols, fonts)
  • Forms and widgets configuration
  • Photo attachments
  • Base maps (if included)

​
Step 5: Connect QField Mobile

Now configure the QField app on your mobile device.
1

Install QField

Download QField from:
2

Configure Cloud Connection

  1. Open QField
  2. Tap the Cloud icon (☁️)
  3. Tap Login
  4. Enter your credentials:
    • Hosted: Use app.qfield.cloud
    • Self-hosted: Enter your instance URL
  5. Enter your username and password
  6. Tap Sign In
3

Download Your Project

  1. In the Cloud Projects list, find your project
  2. Tap the Download icon (⬇️)
  3. Wait for the project to download
  4. Tap the project to open it in QField
The project is now available offline on your device. You can work without an internet connection.

​
Step 6: Collect Field Data

Now you’re ready to collect data in the field!
1

Enable Positioning

  1. Make sure location services are enabled on your device
  2. In QField, tap the GPS icon to start positioning
  3. Wait for GPS accuracy to improve (typically < 5 meters)
2

Add Features

  1. Tap the + button to add a new feature
  2. Select the layer you want to edit
  3. Draw or place your feature on the map
  4. Fill out the attribute form
  5. Add photos or attachments if needed
  6. Tap Save
Changes are saved locally and tracked as “deltas” for later synchronization.
3

Edit Existing Features

  1. Tap an existing feature on the map
  2. Tap Edit
  3. Modify geometry or attributes
  4. Tap Save
4

Work Offline

You can work completely offline. All changes are tracked locally until you sync.

​
Step 7: Synchronize Changes

When you have internet connectivity, sync your changes back to QFieldCloud.
1

Upload Changes from QField

  1. In QField, open the Cloud menu
  2. Tap Synchronize
  3. QField will:
    • Upload all your changes (deltas)
    • Upload any photos or attachments
    • Check for conflicts with other users
  4. Wait for “Sync Complete” message
  • Your local changes (deltas) are uploaded to QFieldCloud
  • Changes from other collaborators are downloaded
  • Conflicts are detected and flagged
  • Attachments are uploaded to cloud storage
  • Your local copy is updated with the latest data
2

View Changes in QGIS

Back at your desk:
  1. Open QFieldSync in QGIS
  2. Click Synchronize to download changes
  3. Your QGIS project is updated with field data
  4. Review changes in QGIS
  5. Make any necessary edits
3

Push Updates to Field

If you made changes in QGIS:
  1. Click Synchronize in QFieldSync
  2. Your updates are uploaded to QFieldCloud
  3. Field workers can sync their QField apps to get the latest data

​
Handling Conflicts

If two users edit the same feature, QFieldCloud detects conflicts.
Conflict Resolution Options:
  • Keep local: Your field changes take precedence
  • Keep remote: Keep the version from QGIS or another user
  • Manual merge: Review and combine changes manually
See Delta Management for detailed conflict handling.

​
Next Steps

Add Collaborators

Invite team members and manage permissions

Create an Organization

Set up an organization for team projects

Explore the API

Integrate QFieldCloud with your workflows

Advanced Features

Learn about advanced sync strategies

​
Troubleshooting

  • Verify your URL is correct (include https://)
  • Check that your API token is valid
  • For self-hosted: ensure SSL certificates are properly configured
  • Check firewall rules if on corporate network
  • Check your storage quota in account settings
  • Ensure all data sources are accessible
  • Try using relative paths instead of absolute paths
  • Check for very large files (>100 MB per file)
  • Ensure you have internet connectivity
  • Check that you’re logged in with the correct account
  • Verify the project exists and you have access
  • Check available storage on your mobile device
  • Review conflicts in the QFieldCloud web interface
  • Resolve conflicts manually if needed
  • Try syncing from QGIS to see detailed error messages
  • See Conflict Resolution
  • Click Synchronize in QFieldSync to download changes
  • Refresh layers in QGIS (Right-click layer → Refresh)
  • Check that you’re viewing the correct project version
  • Verify that changes were successfully uploaded from QField

​
Support

Need help? Check these resources:

Build docs developers (and LLMs) love

Get started for freeTalk to us