p4 unload


Unloads a workspace, label, or task stream to the unload depot or to a flat file.


p4 [g-opts] unload [-f -L -z] [-c client | -l label | -s stream] [-o localFile]
p4 [g-opts] unload [-f -L -z] [-a | -al | -ac] [-d date | -u user]


There are two main uses for the p4 unload command:

  • You can use the command to transfer infrequently-used metadata from the versioning engine's db.* files to a set of flat files in the unload depot. Unloading metadata reduces the size of the working set required by the versioning engine, and on large sites with many years of historical metadata, can offer significant performance improvements.

    Perforce commands such as p4 clients, p4 labels, p4 files, p4 sizes, and p4 fstat ignore unloaded metadata. (To view metadata that has been unloaded, use the -U option with these commands). Most users who use Perforce reporting commands do so with the intent of retrieving a superset of the desired data, and then use automated or manual post-processing to discard the irrelevant lines of output. For example, the p4 clients command (when called without arguments) returns the name of every client workspace ever created by every current and former employee of your organization, even those who left ten years ago. Unloading obsolete metadata is a good way to offer your users a higher signal-to-noise ratio not only in the output of their command-line queries, but also in the amount of information displayed in applications such as P4V.

  • You can use the command with the -o option to unload a client, label, or task stream to a flat file on the client rather than to a file in the unload depot. This can be useful for seeding a client into another database or for creating a private backup of the client. The flat file uses standard journal format. The client, label, or task stream remains fully loaded after the command is run.

Use the -c and -l options to unload a specific client workspace or label. By default, users can only unload their own workspaces or labels; administrators can use the -f option to unload workspaces and labels owned by other users.

You do not need to unload a workspace in preparation for moving it from one edge server to another; running the p4 reload command automatically unloads the specified workspace before reloading it into a new edge server.

Use the -a, -al, or -ac options to indicate that all specified labels and/or client workspaces are to be unloaded. You cannot use these options if you are also using the -o option.

Use the -d date and/or -u user to restrict the unloading operation to labels and/or workspaces older than a specific date, owned by a specific user, or both.

Use the -L option to unload locked workspaces and/or labels. By default, only unlocked labels or workspaces are unloaded.

The access date for a workspace is updated whenever the workspace is used by a command that directly references the workspace. Similarly, the access date for a label is updated when the label is used by a command which directly references that label. The access date for a workspace is also updated when the workspace is used in a revision specifier of the form @workspace, and the access date for a label is updated when the label is used in a revision specifier of the form @labelname.

By default, data in the unload depot is uncompressed. Use -z to store it in compressed form; unloaded metadata is often highly compressible, particularly in continuous build environments characterized by millions of build-associated workspaces labels that are used to perform a single build and then rarely, if ever, accessed again.



Unload all applicable client workspaces and labels; requires -d, -u, or both -d and -u options. This option does not affect task streams.


Unload client workspaces; requires -d, -u, or both -d and -u options.


Unload labels; requires -d, -u, or both -d and -u options.

-c client

Unload the specified client workspace's metadata from db.have (and related tables) and store it in the unload depot.

-d date

Unload metadata older than the specified date.


Force option; administrators can unload workspaces, labels, and task streams owned by other users.

-l label

Unload the specified label from db.label (and related tables) and store it in the unload depot.


Unload a locked workspace, label, or task stream.

-o ouputFile

Unload metadata to a file rather than to the unload depot. Note however that an unload depot must exist for this option to work. This is because the data is first placed in the unload depot and then moved to the output file you specify.

Normal users can only unload objects in their own clients. An administrator can use this option to unload an object owned by other users.

-s stream

Unload the specified task stream. (the stream must be of type task)

-u user

Unload metadata owned by the specified user.


Store the unloaded workspace, label, or task stream in compressed format.


See “Global Options”.

Usage Notes

Can File Arguments Use Revision Specifier?

Can File Arguments Use Revision Range?

Minimal Access Level Required




  • To unload a workspace or label, a user must be able to scan all the files in the workspace's have list and/or files tagged by the label. Administrators should set MaxScanRows and MaxResults high enough (in the p4 group form) that users do not need to ask for assistance with p4 unload or p4 reload operations.

Related Commands

To reload data from the unload depot.

p4 reload