Configuration & operations
Koha independent branches: what IndependentBranches separates
IndependentBranches keeps staff to their own library's items, loans, holds and patron edits. It does not split the catalogue, and it does not hide other libraries' patrons: a permission does that. Tested both ways.
By Babar Junaid
Published 2026-11-21 · Tested against Koha 26.05
The IndependentBranches system preference keeps staff who are not superlibrarians to their own library: they cannot edit another library's items or patrons, check out its copies, or choose another library at login. It does not split the catalogue, and it does not hide other libraries' patrons: that is the view_borrower_infos_from_any_libraries permission.
Koha warns against switching it on a live system
- Switch it on at a quiet time, and tell staff first.
- Check every staff account's permissions (step 2) before, not after.
What changes, tested both ways
We used a Centerville staff account that is not a superlibrarian, a Midway patron and a Midway copy, and ran each action with the preference off and on:
| A Centerville staff member tries to… | With IndependentBranches on |
|---|---|
| Choose a library on the staff login page | No Library: list: everyone logs in at their own library |
| Check out a Midway copy at Centerville | Refused: "This item belongs to Midway and cannot be checked out from this location." |
| Edit a Midway item | Sent back to the record's page; Centerville items still open |
| Edit a Midway patron | Sent back to Patrons; Centerville patrons still open |
| Place a hold for a Centerville patron on a Midway copy | Refused (cannotReserveFromOtherBranches) unless canreservefromotherbranches is on |
| View a Midway patron | Depends on a permission, not on this preference (next section) |
| Edit the bibliographic record only Midway holds | Allowed: records are shared |
| See Midway copies on a record, in the staff interface or the OPAC | Yes: the catalogue is one catalogue |
Superlibrarians are never restricted. A staff member who has the superlibrarian flag "to be safe" makes the whole setting meaningless for that person.
Hiding other libraries' patrons is a permission
This is the question most libraries ask after switching the preference on: "why can our branch staff still see everyone's patrons?" Viewing a patron is decided by the patron sub-permission view_borrower_infos_from_any_libraries, and the full Patrons permission includes it.
| Centerville staff member | Opening the Midway patron |
|---|---|
| Full Patrons permission, IndependentBranches on | Opens |
Patrons sub-permissions without view_borrower_infos_from_any_libraries, IndependentBranches on | Refused: "This account cannot view requested patron information." |
| Same sub-permissions, IndependentBranches off | Also refused |
So to keep patrons apart, give branch staff the patron sub-permissions they need (for example list_borrowers and edit_borrowers) instead of the whole Patrons permission, and leave view_borrower_infos_from_any_libraries unticked. That works with or without IndependentBranches. To let a group of libraries see each other's patrons, put them in a library group with Limit patron data access by group ticked (Administration → Library groups). That only works with IndependentBranches off: with it on, Koha ignores the group and limits staff to their own library's patrons.
Step 1: Switch it on
- 1Go to Administration → System preferences and search for
IndependentBranches. - 2Set "Prevent staff (but not superlibrarians) from modifying objects (holds, items, patrons, etc.) belonging to other libraries" to Yes, and save.
- 3Two related preferences sit under it:
IndependentBranchesPatronModifications(staff only see patron modification requests for their own library) andIndependentBranchesTransfers(staff cannot transfer items to other libraries). Set them to match. - 4Decide on holds: with
canreservefromotherbranchesoff, a patron can only hold copies that belong to their own library.
Step 2: Check every staff account's permissions
- Superlibrarian: only for the people who should see and change everything. The admin password article shows the query that lists them.
- Patrons: sub-permissions without
view_borrower_infos_from_any_libraries, as above. loggedinlibrary(Allow staff to change logged in library): leave it off for branch staff. In the run, a staff member with it used Set library to switch to Midway and could then edit Midway items and Midway patrons. The checks look at the library someone is logged in at, not at their home library.
One Koha has one catalogue. Bibliographic records belong to no library, so any staff member allowed to catalogue can edit a record, including one only another library holds. Every copy shows on the record in the staff interface and on the OPAC, whatever the preference. A branch OPAC address (see a separate OPAC for each branch) only changes the default search scope.
If two libraries need their own catalogues, staff and patrons that the other cannot see, that is a second Koha instance on the same server (koha-create), with its own database. What it costs: no shared catalogue or shared patrons between them, a second set of preferences, rules and notices to keep up, and both instances upgrade together, because one koha-common package serves every instance on the server.
Each instance gets its own address. By default the instance name is part of the hostname (library.example.org, library-intra.example.org), set by /etc/koha/koha-sites.conf. That file can also put each instance on its own port instead (OPACPORT and INTRAPORT), read when koha-create runs. Some consortia run several instances on one server this way, one per member library, each with its own data.
| What the libraries need | The setup |
|---|---|
| Departmental or campus branches sharing one catalogue and one set of patrons (Koha's normal way of working) | Branches in one Koha: adding a library branch |
| One address, but each branch keeps to its own patrons, loans and items | Branches in one Koha with IndependentBranches and the permissions on this page |
| Fully separate libraries on one server, each with its own address or port | One Koha instance per library |
Not sure which one fits, or short of time to set it up?
How to undo it
Set IndependentBranches back to No. The preference deletes and moves nothing, so the restrictions simply stop. Patron visibility stays as the permissions say.
Why it works this way
IndependentBranches is not one wall around a library. It is a check repeated in each place that changes something: checkout (C4/Circulation.pm), holds (C4/Reserves.pm), the item editor, the patron editor, notices, suggestions, serials. Each of those compares the object's library with the library the staff member is logged in at. Reading the catalogue was never part of it, because Koha's records are one shared catalogue by design.
Patron visibility is a permission and a library-group feature, so that a consortium can share patrons within a group and hide them from others. It is checked by a different function, against the staff member's home library. That is why the two can disagree: after Set library, the editing checks follow the new library while viewing still follows the home one.
Troubleshooting
| What you see | Why, and what to do |
|---|---|
| "This item belongs to Midway and cannot be checked out from this location." | IndependentBranches is on and the copy belongs to another library. Return or transfer it there, or ask a superlibrarian |
| "This account cannot view requested patron information." | The staff account lacks view_borrower_infos_from_any_libraries (with the preference on or off) |
| Branch staff still see every library's patrons | They hold the full Patrons permission or are superlibrarians. Give them sub-permissions instead |
| Opening an item for editing jumps back to the record | The item belongs to another library |
| Opening a patron for editing jumps back to Patrons | The patron belongs to another library |
| A branch staff member can still edit another library's items | Superlibrarian, or loggedinlibrary plus Set library |
| The login page lost its Library: list | Expected with IndependentBranches on |
Adding the libraries themselves is covered in adding a library branch.
Tested on live Koha 26.05.02
Passed all 25 checks · Read the run log
- Koha release
- 26.05.02
- System
- Debian 13 (trixie)
- Setup
- Official Koha test container (koha-common commands). A command that needs systemd or a firewall says where it ran.
- Source read at
- Koha commit d3fc229
Earlier live checks (1)
- , Koha 26.05.02 (commit d3fc229): all 24 claims held. Read the run log
In the Koha manual (26.05)
Verified against the Koha source (13 files)
- koha-tmpl/intranet-tmpl/prog/en/modules/admin/preferences/admin.pref (lines 129-150)
- C4/Context.pm (lines 863-876)
- Koha/Patron.pm (lines 2209-2290, 2334-2356, 2409-2450)
- C4/Circulation.pm (lines 1176-1185)
- koha-tmpl/intranet-tmpl/prog/en/modules/circ/circulation.tt (lines 680-682)
- C4/Reserves.pm (lines 521-529)
- cataloguing/additem.pl (lines 172-178)
- members/memberentry.pl (lines 409-415, 708-716)
- C4/Output.pm (lines 339-368)
- koha-tmpl/intranet-tmpl/prog/en/includes/blocking_errors.inc (lines 5-6)
- koha-tmpl/intranet-tmpl/prog/en/modules/auth.tt (lines 180-200)
- circ/set-library.pl (lines 55-70)
- debian/templates/koha-sites.conf (lines 6-14)
The label under each command says where its response came from; a command with no label was not run live. How we test and which standards we follow.
Not sure whether your branches need one Koha or several? We set up branch separation, permissions or separate instances on your own server.
Want your staff trained on this? We teach it hands on with a live Koha, online or at your library. Ask about staff training
Related
More on configuration & operations
Answers to the questions that usually arrive with this one.
How to add a library (branch) in Koha
Adding a branch to Koha takes one form, but the code you choose is permanent and a new library needs a calendar, circulation rules and staff before it can lend. Here is the form, every field that matters, and what to set up next.
Koha background jobs stay at "New" and never finish
A staged MARC import or batch modification that sits at "New" means no worker is taking jobs from that queue. Start the worker for both queues and the jobs run.
Koha search says "No results found" for everything
When every search in Koha finds nothing, the records are almost always fine and the search engine is not answering. Here is how to find which part stopped and bring it back, for Zebra and Elasticsearch.
How to edit notices and slips in Koha (templates and variables)
Every email, SMS and printed slip Koha sends comes from a template in Tools → Notices and slips. Here is how to edit one, add the patron’s name or the due date with a variable, give one library its own wording, and test it before it reaches a patron.

