Skip to main content
This guide walks you through installing PocketBase, starting the server, and creating your first database collection. You’ll have a working REST API in under 5 minutes.

​
Prerequisites

No dependencies required! PocketBase is a single executable that runs on macOS, Linux, Windows, and FreeBSD.

​
Start your first instance

1

Download and extract

Download the latest release for your platform from GitHub:
# Download (replace VERSION with the latest version)
wget https://github.com/pocketbase/pocketbase/releases/download/vVERSION/pocketbase_VERSION_linux_amd64.zip

# Extract
unzip pocketbase_VERSION_linux_amd64.zip

# Make executable
chmod +x pocketbase
2

Start the server

Run PocketBase with the serve command:
./pocketbase serve
You’ll see output like this:
Server started at: http://127.0.0.1:8090
  - REST API: http://127.0.0.1:8090/api/
  - Admin UI: http://127.0.0.1:8090/_/
PocketBase creates a pb_data directory to store your database and uploaded files. You can customize this with the --dir flag.
3

Create your admin account

Open your browser and navigate to:
http://127.0.0.1:8090/_/
You’ll be prompted to create an admin account. Fill in your email and password—this account lets you manage your database through the Admin UI.
4

Create your first collection

In the Admin UI:
  1. Click New Collection in the sidebar
  2. Choose Base collection (for regular database records)
  3. Name it posts
  4. Click Create
Now add some fields:
  • Click New field and select Plain text
  • Name: title, Check Required
  • Add another Editor field named content
  • Click Save
PocketBase automatically adds id, created, and updated fields to every collection.
5

Test your API

Your REST API is automatically available. Try creating a record:
curl -X POST http://127.0.0.1:8090/api/collections/posts/records \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My first post",
    "content": "Hello from PocketBase!"
  }'
Fetch all records:
curl http://127.0.0.1:8090/api/collections/posts/records
You should see your newly created post in the JSON response.

​
Build with the Go library

If you want to extend PocketBase with custom logic, you can use it as a Go library. Here’s a minimal example based on the official source:
1

Set up your Go project

mkdir myapp && cd myapp
go mod init myapp
2

Create main.go

Create a main.go file with this code from the PocketBase examples:
main.go
package main

import (
    "log"

    "github.com/pocketbase/pocketbase"
    "github.com/pocketbase/pocketbase/core"
)

func main() {
    app := pocketbase.New()

    app.OnServe().BindFunc(func(se *core.ServeEvent) error {
        // registers new "GET /hello" route
        se.Router.GET("/hello", func(re *core.RequestEvent) error {
            return re.String(200, "Hello world!")
        })

        return se.Next()
    })

    if err := app.Start(); err != nil {
        log.Fatal(err)
    }
}
This example:
  • Creates a new PocketBase instance with pocketbase.New()
  • Hooks into the OnServe() event to add a custom route
  • Registers a GET /hello endpoint that returns “Hello world!”
  • Starts the application with app.Start()
3

Install dependencies and run

go mod tidy
go run main.go serve
Your server starts with both the standard PocketBase API and your custom /hello route.
4

Test your custom route

curl http://127.0.0.1:8090/hello
You should see: Hello world!
5

Build for production

Create a statically linked executable:
CGO_ENABLED=0 go build
Then deploy your single binary:
./myapp serve

​
Advanced example with plugins

The official PocketBase executable (from releases) is built with additional plugins. Here’s what the full examples/base/main.go includes: 
// Enable JavaScript hooks from pb_hooks directory
jsvm.MustRegister(app, jsvm.Config{
    MigrationsDir: migrationsDir,
    HooksDir:      hooksDir,
    HooksWatch:    hooksWatch,
    HooksPoolSize: hooksPool,
})
The prebuilt executables include all these plugins, allowing you to extend PocketBase with JavaScript without writing Go code.

​
Common commands

PocketBase includes several built-in commands:
CommandDescription
serveStart the HTTP server (default port: 8090)
superuserCreate or update a superuser account
migrateRun database migrations (when using Go library)
--helpShow available commands and flags

​
Create a superuser via CLI

./pocketbase superuser create [email protected] password123

​
Use a custom port

./pocketbase serve --http=0.0.0.0:3000

​
Enable development mode

./pocketbase serve --dev
Development mode enables:
  • Verbose logging to console
  • SQL query logging
  • Detailed error messages
Don’t use --dev in production—it exposes sensitive information in logs.

​
SDK integration

Connect to your PocketBase API from the frontend using the official SDKs: 
import PocketBase from 'pocketbase';

const pb = new PocketBase('http://127.0.0.1:8090');

// Create a record
const record = await pb.collection('posts').create({
    title: 'My first post',
    content: 'Hello from PocketBase!'
});

// Fetch records
const records = await pb.collection('posts').getFullList();

// Subscribe to realtime changes
pb.collection('posts').subscribe('*', (e) => {
    console.log(e.action); // create, update, delete
    console.log(e.record);
});

​
Next steps

Database collections

Learn about collection types, fields, and relations

Authentication

Set up user authentication and OAuth2 providers

File uploads

Handle file uploads and image transformations

Extend with Go

Add custom business logic and API routes

​
Troubleshooting

​
Port already in use

If port 8090 is busy, specify a different port: 
./pocketbase serve --http=0.0.0.0:8091

​
Permission denied on Linux/macOS

Make the executable runnable: 
chmod +x pocketbase

​
Database locked error

This happens if multiple PocketBase instances try to access the same pb_data directory. Only run one instance per data directory, or use different --dir paths: 
./pocketbase serve --dir=./pb_data_instance1
For production deployments, consider using process managers like systemd, Docker, or PM2 to keep PocketBase running reliably.

Build docs developers (and LLMs) love

Get started for freeTalk to us