2019-08-07 19:15:50 +03:00
|
|
|
[![PyPi Release](https://img.shields.io/pypi/v/maestral.svg)](https://pypi.org/project/maestral/)
|
|
|
|
[![Pyversions](https://img.shields.io/pypi/pyversions/maestral.svg)](https://pypi.org/pypi/maestral/)
|
2019-07-16 14:28:37 +03:00
|
|
|
|
2020-02-28 02:08:18 +03:00
|
|
|
# Maestral <img src="https://raw.githubusercontent.com/SamSchott/maestral-dropbox/master/maestral/resources/maestral.png" align="right" title="Maestral" width="110" height="110">
|
2019-07-16 14:28:37 +03:00
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
A light-weight and open-source Dropbox client for macOS and Linux.
|
2018-11-26 18:50:02 +03:00
|
|
|
|
2018-11-26 18:56:32 +03:00
|
|
|
## About
|
2019-07-16 21:37:21 +03:00
|
|
|
|
2019-07-24 17:12:21 +03:00
|
|
|
Maestral is an open-source Dropbox client written in Python. The project's main goal is to
|
2019-07-16 21:37:21 +03:00
|
|
|
provide a client for platforms and file systems that are no longer directly supported by
|
|
|
|
Dropbox.
|
2018-11-26 18:50:02 +03:00
|
|
|
|
2020-03-20 03:31:22 +03:00
|
|
|
Maestral currently does not support Dropbox Paper, the management of Dropbox teams and
|
2019-07-16 21:37:21 +03:00
|
|
|
the management of shared folder settings. If you need any of this functionality, please
|
2020-03-20 03:31:22 +03:00
|
|
|
use the Dropbox website or the official client. Maestral does support the syncing of
|
|
|
|
multiple Dropbox accounts and excluding local files from sync with a ".mignore" file.
|
2019-07-16 21:37:21 +03:00
|
|
|
|
2019-10-04 23:32:24 +03:00
|
|
|
The focus on "simple" file syncing does come with advantages: on macOS, the Maestral App
|
|
|
|
bundle is 80% smaller than the official Dropbox app (50 MB vs 290 MB) and uses much less
|
2019-11-25 02:00:38 +03:00
|
|
|
memory (100 MB vs 800 MB for a medium sized Dropbox on macOS). The memory usage will
|
|
|
|
depend on the size of your synced Dropbox folder and can be further reduced when running
|
|
|
|
Maestral without a GUI.
|
2019-07-11 18:12:37 +03:00
|
|
|
|
2020-03-19 22:25:35 +03:00
|
|
|
Maestral uses the public Dropbox API which, unlike their own client, does not support
|
2020-03-08 02:45:45 +03:00
|
|
|
syncing only those parts of a file which changed ("binary diff"). Maestral therefore may
|
|
|
|
use more bandwidth that the official client. However, it will never upload or download a
|
|
|
|
file if it already exists with the same content locally and in the cloud and it will
|
|
|
|
sync moved files or folders without transferring any files whenever possible.
|
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
## Installation
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2019-08-07 19:15:50 +03:00
|
|
|
A binary is provided for macOS High Sierra and higher and can be downloaded from the
|
2020-01-08 00:17:46 +03:00
|
|
|
Releases tab. On other platforms, please download and install the Python package from PyPI:
|
2019-06-15 22:57:17 +03:00
|
|
|
```console
|
2019-07-26 00:47:23 +03:00
|
|
|
$ python3 -m pip install --upgrade maestral
|
2019-06-15 22:57:17 +03:00
|
|
|
```
|
2020-02-28 15:22:55 +03:00
|
|
|
If you intend to use the graphical user interface, you also need to specify the GUI option
|
|
|
|
during installation. This will install the `maestral-qt` frontend and `PyQt5`:
|
2019-06-25 21:29:01 +03:00
|
|
|
```console
|
2020-02-28 15:22:55 +03:00
|
|
|
$ python3 -m pip install --upgrade maestral[gui]
|
2019-06-25 21:29:01 +03:00
|
|
|
```
|
2020-02-28 15:22:55 +03:00
|
|
|
More detailed installation instructions are given in the
|
|
|
|
[Wiki](https://github.com/SamSchott/maestral-dropbox/wiki/Installation-Requirements).
|
2018-12-02 03:26:41 +03:00
|
|
|
|
2018-12-08 20:05:55 +03:00
|
|
|
## Usage
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2019-07-24 17:12:21 +03:00
|
|
|
Run `maestral gui` in the command line (or open the Maestral app on macOS) to start
|
|
|
|
Maestral with a graphical user interface. On its first run, Maestral will guide you
|
2019-07-16 21:37:21 +03:00
|
|
|
through linking and configuring your Dropbox and will then start syncing.
|
2018-12-08 15:50:42 +03:00
|
|
|
|
2020-03-19 22:25:35 +03:00
|
|
|
![screenshot macOS](https://raw.githubusercontent.com/SamSchott/maestral-dropbox/master/screenshots/macOS_light.png)
|
2019-08-11 18:28:08 +03:00
|
|
|
![screenshot Fedora](https://raw.githubusercontent.com/SamSchott/maestral-dropbox/master/screenshots/Ubuntu.png)
|
2018-12-08 19:43:39 +03:00
|
|
|
|
2019-06-15 22:57:17 +03:00
|
|
|
## Command line usage
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2019-07-24 17:12:21 +03:00
|
|
|
After installation, Maestral will be available as a command line script by typing
|
2019-08-15 00:20:53 +03:00
|
|
|
`maestral` in the command prompt. Type `maestral --help` to get a full list of available
|
|
|
|
commands. The most important are:
|
2019-08-13 17:24:39 +03:00
|
|
|
|
2019-09-08 18:52:16 +03:00
|
|
|
- `maestral gui`: Starts the Maestral GUI. Creates a sync daemon if not already running.
|
2019-09-15 14:56:07 +03:00
|
|
|
- `maestral start|stop`: Starts or stops the Maestral sync daemon.
|
|
|
|
- `maestral pause|resume`: Pauses or resumes syncing.
|
2020-02-28 15:22:55 +03:00
|
|
|
- `maestral autostart`: Sets the daemon to start on log in.
|
2019-09-15 16:36:34 +03:00
|
|
|
- `maestral status`: Gets the current status of Maestral.
|
|
|
|
- `maestral file-status LOCAL_PATH`: Gets the sync status of an individual file or folder.
|
2019-09-15 14:56:07 +03:00
|
|
|
- `maestral excluded add|remove|list`: Command group to manage excluded folders.
|
2019-09-15 16:36:34 +03:00
|
|
|
- `maestral ls DROPBOX_PATH`: Lists the contents of a directory on Dropbox.
|
2020-02-28 15:22:55 +03:00
|
|
|
- `maestral notify snooze N`: Snoozes desktop notifications for N minutes.
|
2019-08-13 17:24:39 +03:00
|
|
|
|
2019-08-14 21:43:25 +03:00
|
|
|
Maestral currently supports the syncing of multiple Dropbox accounts by running multiple
|
2020-02-28 15:22:55 +03:00
|
|
|
instances with different configuration files. This needs to be configured from the
|
|
|
|
command line by passing the option `--config-name` to `maestral start` or `maestral gui`.
|
|
|
|
Maestral will then select an existing config with the given name or create a new one.
|
|
|
|
For example:
|
|
|
|
|
|
|
|
```console
|
|
|
|
$ maestral start --config-name="personal"
|
|
|
|
$ maestral start --config-name="work"
|
2018-12-02 03:26:41 +03:00
|
|
|
```
|
2019-08-15 00:23:58 +03:00
|
|
|
This will start two instances of Maestral, syncing a private and a work account,
|
2020-02-28 15:22:55 +03:00
|
|
|
respectively. Configs will be automatically cleared when unlinking an account and you can
|
|
|
|
list all currently linked accounts with `maestral configs`:
|
|
|
|
|
|
|
|
```console
|
|
|
|
$ maestral configs
|
|
|
|
|
|
|
|
Config name Account
|
|
|
|
personal user@gmail.com
|
|
|
|
work user@mycorp.org
|
|
|
|
|
|
|
|
```
|
2019-08-14 21:43:25 +03:00
|
|
|
|
|
|
|
By default, the Dropbox folder names will contain the capitalised config-name in braces.
|
|
|
|
In the above case, this will be "Dropbox (Personal)" and "Dropbox (Work)".
|
2019-06-15 22:57:17 +03:00
|
|
|
|
|
|
|
## Contribute
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2020-04-03 16:51:35 +03:00
|
|
|
A documentation for developers is available at
|
2020-04-03 16:54:48 +03:00
|
|
|
[https://maestral-dropbox.readthedocs.io](https://maestral-dropbox.readthedocs.io).
|
2019-06-26 22:09:37 +03:00
|
|
|
The following tasks could need your help:
|
2019-06-15 22:57:17 +03:00
|
|
|
|
2020-03-23 16:44:57 +03:00
|
|
|
- [ ] Packaging for non-macOS platforms.
|
2019-08-14 21:43:25 +03:00
|
|
|
- [ ] Write tests for Maestral.
|
2020-02-28 15:22:55 +03:00
|
|
|
- [ ] A native GTK frontend. Maestral currently uses PyQt5.
|
2018-11-28 00:29:49 +03:00
|
|
|
|
2020-02-28 15:29:43 +03:00
|
|
|
## Warning
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2020-03-04 16:21:19 +03:00
|
|
|
- Maestral is still in beta status. Even though unlikely, using it may potentially
|
2019-07-09 21:27:49 +03:00
|
|
|
result in loss of data.
|
2019-08-07 19:15:50 +03:00
|
|
|
- Network drives and some external hard drives are not supported as locations for the
|
|
|
|
Dropbox folder.
|
2018-11-28 00:23:00 +03:00
|
|
|
|
|
|
|
## Dependencies
|
2019-07-09 19:19:49 +03:00
|
|
|
|
2019-08-14 21:43:25 +03:00
|
|
|
- macOS (10.13 or higher for binary) or Linux
|
2019-07-09 19:19:49 +03:00
|
|
|
- Python 3.6 or higher
|
2019-08-14 21:43:25 +03:00
|
|
|
- For the GUI only:
|
|
|
|
- PyQt 5.9 or higher
|
|
|
|
- [gnome-shell-extension-appindicator](https://github.com/ubuntu/gnome-shell-extension-appindicator)
|
|
|
|
on Gnome 3.26 and higher
|
2019-07-22 19:22:22 +03:00
|
|
|
|
|
|
|
# Acknowledgements
|
|
|
|
|
2020-03-04 16:21:19 +03:00
|
|
|
- The config module uses code from the [Spyder IDE](https://github.com/spyder-ide)
|
2020-03-04 16:26:15 +03:00
|
|
|
- The MaestralApiClient is based on work from [Orphilia](https://github.com/ksiazkowicz/orphilia-dropbox)
|
2020-03-04 16:25:40 +03:00
|
|
|
- Error reporting is powered by bugsnag:
|
2020-01-08 17:22:37 +03:00
|
|
|
|
2020-03-04 16:25:40 +03:00
|
|
|
<a href="https://bugsnag.com"> <img src="https://global-uploads.webflow.com/5c741219fd0819540590e785/5c741219fd0819856890e790_asset%2039.svg" title="Bugsnag text" height="20"></a>
|
2020-01-08 17:22:37 +03:00
|
|
|
|